@cosmicdrift/kumiko-bundled-features 0.388.0 → 0.389.0

package/dist/host-routing/validate-options.js

@@ -11,6 +11,9 @@ function validateRedirects(options) {
         if (!REDIRECT_PATH_PATTERN.test(rule.from)) {
             throw new Error(`host-routing: redirect from must be a path like "/old", got "${rule.from}"`);
         }
+        if (rule.from === "/api" || rule.from.startsWith("/api/")) {
+            throw new Error(`host-routing: redirect from must not be an /api path, it would never fire, got "${rule.from}"`);
+        }
         if (!REDIRECT_TARGET_PATTERN.test(rule.to)) {
             throw new Error(`host-routing: redirect to must be a same-origin path or an https URL without query, got "${rule.to}"`);
         }

package/dist/inbound-mail-foundation/feature.js

@@ -58,6 +58,7 @@ import { mailAccountEditScreen, mailAccountListScreen } from "./screens.js";
 import { INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON, inboundMessageTenantDestroyHook, mailAccountTenantDestroyHook, mailThreadTenantDestroyHook, } from "./tenant-destroy-hook.js";
 export function createInboundMailFoundationFeature() {
     return defineFeature(INBOUND_MAIL_FOUNDATION_FEATURE, (r) => {
+        r.adoptsBundledLists();
         r.describe("Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.");
         r.uiHints({
             displayLabel: "Inbound Mail · Foundation",

package/dist/jobs/feature.js

@@ -25,6 +25,7 @@ export function createJobsFeature(options = {}) {
         throw new Error(`createJobsFeature: readRoles must not contain "anonymous" — job status and failures are only readable by members of the tenant.`);
     }
     return defineFeature("jobs", (r) => {
+        r.adoptsBundledLists();
         r.describe("Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops `queued` rows older than `retentionDays`.");
         r.uiHints({
             displayLabel: "Jobs · Audit & Operator UI",

package/dist/ledger/web/index.js

@@ -1,7 +1,7 @@
 // Client-safe ledger surface: QN constants, pure recurring helpers
 // (projection + Soll/Ist merge), and Zod payload schemas for client-side
 // pre-validation before dispatch. The full `../ledger` entry also re-exports
-// the feature/handlers/executor, which pull postgres-js; importing it in a
+// the feature/handlers/executor, which pull the DB driver; importing it in a
 // browser bundle fails on Node builtins. Client screens import dispatch QNs and
 // pure forecast/merge helpers from this module, then dispatch via the renderer's
 // useDispatcher.

package/dist/legal-pages/seed.d.ts

@@ -9,4 +9,6 @@ export type LegalContentSeedSource = {
 export type LegalContentSeedFn = (deps: {
     readonly db: DbConnection;
 }) => Promise<void>;
-export declare function legalContentSeed(source: LegalContentSeedSource): LegalContentSeedFn;
+export declare function legalContentSeed(source: LegalContentSeedSource, options?: {
+    readonly folder?: string;
+}): LegalContentSeedFn;

package/dist/legal-pages/seed.js

@@ -28,11 +28,11 @@ async function loadBlocksFromJson(path) {
 }
 // Boot seed for runProdApp's `seeds: [...]`. The JSON template is authoritative
 // (ifExists "update"), so legally required text changes reach rows seeded once.
-export function legalContentSeed(source) {
+export function legalContentSeed(source, options) {
     return async ({ db }) => {
         const blocks = "blocks" in source
             ? legalContentBlocksSchema.parse(source.blocks)
             : await loadBlocksFromJson(source.path);
-        await seedLegalContentFromJson(db, blocks);
+        await seedLegalContentFromJson(db, blocks, options);
     };
 }

package/dist/mail-transport-smtp/config-keys.js

@@ -4,6 +4,7 @@ import { access, createTenantConfig } from "@cosmicdrift/kumiko-framework/engine
 const tenantAdminWrite = access.withSystem(access.roles("TenantAdmin"));
 const tenantAdminRead = access.roles("TenantAdmin", "SystemAdmin");
 // required: true ↔ the requireNonEmpty calls in buildSmtpTransport — keep in sync.
+// authUser stays optional: empty means an unauthenticated relay.
 export const SMTP_CONFIG_KEYS = {
     host: createTenantConfig("text", {
         required: true,
@@ -39,7 +40,6 @@ export const SMTP_CONFIG_KEYS = {
         },
     }),
     authUser: createTenantConfig("text", {
-        required: true,
         default: "",
         write: tenantAdminWrite,
         read: tenantAdminRead,

package/dist/mail-transport-smtp/feature.js

@@ -76,8 +76,7 @@ export function createMailTransportSmtpFeature() {
                 return `${plaintext.slice(0, 3)}...${plaintext.slice(-2)}`;
             },
             scope: "tenant",
-            // required: true ↔ the missing-secret throw in readPassword — keep in sync.
-            required: true,
+            // Only needed once authUser is set (readPassword throws then), so readiness must not demand it.
         });
         const configKeys = r.config({ keys: SMTP_CONFIG_KEYS });
         r.translations({ keys: MAIL_TRANSPORT_SMTP_I18N });
@@ -126,8 +125,10 @@ async function buildSmtpTransport(ctx, tenantId) {
     const port = requireDefined(await ctxConfig(sharedMailTransportSmtpFeature.exports.configKeys.port), FEATURE_NAME, "port"); // @cast-boundary engine-payload
     const secure = requireDefined(await ctxConfig(sharedMailTransportSmtpFeature.exports.configKeys.secure), FEATURE_NAME, "secure"); // @cast-boundary engine-payload
     const from = requireNonEmpty(await ctxConfig(sharedMailTransportSmtpFeature.exports.configKeys.from), FEATURE_NAME, "from", SMTP_HINT);
-    const authUser = requireNonEmpty(await ctxConfig(sharedMailTransportSmtpFeature.exports.configKeys.authUser), FEATURE_NAME, "authUser", SMTP_HINT);
-    const password = await readPassword(ctx, tenantId);
+    const authUser = (await ctxConfig(sharedMailTransportSmtpFeature.exports.configKeys.authUser))?.trim();
+    const auth = authUser === undefined || authUser === ""
+        ? undefined
+        : { user: authUser, pass: await readPassword(ctx, tenantId) };
     let target;
     try {
         target = await resolveMailConnectTarget(host, {
@@ -155,7 +156,7 @@ async function buildSmtpTransport(ctx, tenantId) {
         port,
         secure,
         from,
-        auth: { user: authUser, pass: password },
+        ...(auth && { auth }),
         ...(target.servername && { servername: target.servername }),
     });
 }

package/dist/managed-pages/constants.d.ts

@@ -0,0 +1 @@
+export declare const MANAGED_PAGES_FEATURE: "managed-pages";

package/dist/managed-pages/constants.js

@@ -0,0 +1 @@
+export const MANAGED_PAGES_FEATURE = "managed-pages";

package/dist/managed-pages/feature.js

@@ -4,6 +4,7 @@ import { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
 import { cachedSecurePageResponse, EMPTY_BRANDING, renderSafeMarkdown, wrapInLayout, } from "../page-render/index.js";
 import { rateLimitedTextResponse } from "../shared/index.js";
 import { BRANDING_KEYS, BRANDING_QUERY_QN, CUSTOM_CSS_KEY, coerceBranding } from "./branding.js";
+import { MANAGED_PAGES_FEATURE } from "./constants.js";
 import { createBrandingQuery } from "./handlers/branding.query.js";
 import { bySlugQuery } from "./handlers/by-slug.query.js";
 import { byTenantPublishedQuery } from "./handlers/by-tenant-published.query.js";
@@ -79,7 +80,8 @@ export function createManagedPagesFeature(opts) {
     const basePath = opts.basePath ?? "/p";
     const defaultLang = opts.defaultLang ?? "en";
     const allowCustomCss = opts.allowCustomCss ?? false;
-    return defineFeature("managed-pages", (r) => {
+    return defineFeature(MANAGED_PAGES_FEATURE, (r) => {
+        r.adoptsBundledLists();
         r.describe("Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.");
         r.uiHints({
             displayLabel: "Managed Pages · Public CMS",

package/dist/managed-pages/index.d.ts

@@ -1,5 +1,6 @@
 export { type BrandingTokens, brandingHeaderHtml, brandingStyleBlock, EMPTY_BRANDING, sanitizeTenantCss, TENANT_CONTENT_ATTR, tenantStyleBlock, } from "../page-render/index.ts";
 export { BRANDING_QN, MANAGED_PAGES_CSS_FEATURE } from "./branding.ts";
+export { MANAGED_PAGES_FEATURE } from "./constants.ts";
 export { createManagedPagesCssFeature } from "./css-gate.ts";
 export { createManagedPagesFeature, type ManagedPagesOptions, type ManagedPagesWrapLayout, } from "./feature.ts";
 export { type PageRow, pageEntity, pagesTable } from "./table.ts";

package/dist/managed-pages/index.js

@@ -13,6 +13,7 @@ export { brandingHeaderHtml, brandingStyleBlock, EMPTY_BRANDING, sanitizeTenantC
 // (`config:write:set`) — single source for the `managed-pages:config:branding-*`
 // strings, so apps + the per-tenant migration never hardcode them.
 export { BRANDING_QN, MANAGED_PAGES_CSS_FEATURE } from "./branding.js";
+export { MANAGED_PAGES_FEATURE } from "./constants.js";
 export { createManagedPagesCssFeature } from "./css-gate.js";
 export { createManagedPagesFeature, } from "./feature.js";
 export { pageEntity, pagesTable } from "./table.js";

package/dist/notes-history/handlers/add-note.write.js

@@ -51,7 +51,7 @@ export function createAddNoteHandler(access = DEFAULT_NOTES_HISTORY_ACCESS, entr
             let authorName = null;
             try {
                 // read_users is tenant-agnostic → ctx.db.unsafeRaw, not the tenant-scoped ctx.db.
-                // postgres-js poisons the whole tx after any error inside it, even one that's
+                // Postgres aborts the whole tx after any error inside it, even one that's
                 // caught — so the lookup runs in a savepoint where available, otherwise directly
                 // (pool statements are their own units).
                 authorName = await runInSavepointIfSupported(ctx.db.unsafeRaw(), async (sp) => {

package/dist/personal-access-tokens/feature.js

@@ -41,6 +41,7 @@ export function bindPatAutoRevokeOnPasswordChangeFromFeature(feature) {
 export function createPersonalAccessTokensFeature(options) {
     const { scopes } = options;
     return defineFeature(PAT_FEATURE, (r) => {
+        r.adoptsBundledLists();
         r.describe("Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.");
         r.uiHints({ displayLabel: "Personal Access Tokens", category: "identity", recommended: false });
         // Opt-in tier-gating (mirrors ledger/tags): when set, the feature declares

package/dist/secrets/write-gate.js

@@ -6,6 +6,10 @@ function unknownKeyFailure(key) {
         failure: writeFailure(new NotFoundError("secretKey", key, { i18nKey: SECRETS_ERROR_KEYS.unknownKey })),
     };
 }
+function isUnderMountedFeaturePrefix(registry, key) {
+    const separator = key.indexOf(":");
+    return separator > 0 && registry.getFeature(key.slice(0, separator)) !== undefined;
+}
 function namespaceAcceptsKey(namespace, key) {
     const suffix = key.slice(namespace.qualifiedPrefix.length);
     if (suffix.length === 0)
@@ -16,13 +20,15 @@ function namespaceAcceptsKey(namespace, key) {
 // are writable through the API, so a tenant admin cannot plant arbitrary rows
 // next to the feature-owned ones. writeRoles narrows the handler access
 // further for a key or a whole namespace. Delete passes allowUndeclared: it
-// creates nothing, and legacy rows under since-undeclared keys must stay removable.
+// creates nothing, and legacy rows under since-undeclared keys must stay removable,
+// unless the key sits under a mounted feature's prefix: those rows belong to the
+// feature and must not be removable by a tenant admin outside its writeRoles.
 export function checkSecretKeyWrite(registry, userRoles, key, options = {}) {
     const keyDef = registry.getSecretKey(key);
     const namespace = keyDef ? undefined : registry.findSecretNamespace(key);
     if (!keyDef &&
         !(namespace && namespaceAcceptsKey(namespace, key)) &&
-        options.allowUndeclared !== true) {
+        (options.allowUndeclared !== true || isUnderMountedFeaturePrefix(registry, key))) {
         return unknownKeyFailure(key);
     }
     const writeRoles = keyDef?.writeRoles ?? namespace?.writeRoles;

package/dist/sessions/feature.js

@@ -48,6 +48,7 @@ export function bindAutoRevokeFromFeature(feature) {
 export function createSessionsFeature(options) {
     return defineFeature("sessions", (r) => {
         const adminRoles = access[options?.adminAccess ?? "admin"];
+        r.adoptsBundledLists();
         r.describe("Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the same callbacks are also registered as an auth-foundation sessionStore provider, resolvable generically via `resolveSessionStore()`. The feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.");
         r.uiHints({
             displayLabel: "Sessions · Server-side Logout",

package/dist/sessions/index.d.ts

@@ -3,6 +3,6 @@ export type { BindAutoRevokeOnPasswordChange, SessionsFeatureOptions } from "./f
 export { bindAutoRevokeFromFeature, createSessionsFeature } from "./feature.ts";
 export { userSessionEntity, userSessionTable } from "./schema/user-session.ts";
 export type { SessionCallbacks, SessionCallbacksOptions, SessionMassRevoker, } from "./session-callbacks.ts";
-export { createSessionCallbacks, isPrincipalBlocked } from "./session-callbacks.ts";
+export { createSessionCallbacks } from "./session-callbacks.ts";
 export type { SessionRevokedPayload } from "./session-revoked-event.ts";
 export { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN, SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema, } from "./session-revoked-event.ts";

package/dist/sessions/index.js

@@ -1,5 +1,5 @@
 export { DEFAULT_SESSION_CACHE_TTL_MS, DEFAULT_SESSION_EXPIRY_MS, SESSION_MINE_SCREEN_ID, SESSIONS_FEATURE, SessionErrors, SessionHandlers, SessionQueries, } from "./constants.js";
 export { bindAutoRevokeFromFeature, createSessionsFeature } from "./feature.js";
 export { userSessionEntity, userSessionTable } from "./schema/user-session.js";
-export { createSessionCallbacks, isPrincipalBlocked } from "./session-callbacks.js";
+export { createSessionCallbacks } from "./session-callbacks.js";
 export { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN, SESSION_REVOKED_EVENT_SHORT, sessionRevokedSchema, } from "./session-revoked-event.js";

package/dist/sessions/session-callbacks.d.ts

@@ -1,8 +1,6 @@
 import type { SessionChecker, SessionCreator, SessionMassRevoker, SessionRevoker } from "@cosmicdrift/kumiko-framework/api";
 export type { SessionMassRevoker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { isPrincipalBlocked } from "../user/index.ts";
-export { isPrincipalBlocked };
 export type SessionAllOthersRevoker = (userId: string, currentSid: string | undefined) => Promise<number>;
 export type SessionCallbacksOptions = {
     readonly db: DbConnection;

package/dist/sessions/session-callbacks.js

@@ -5,12 +5,10 @@ import { generateId, parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { encryptForDirectWrite } from "../shared/index.js";
 import { tenantMembershipsTable } from "../tenant/index.js";
-import { isPrincipalBlocked, isPrincipalRowBlocked, userTable, } from "../user/index.js";
+import { isPrincipalRowBlocked, userTable } from "../user/index.js";
 import { DEFAULT_SESSION_EXPIRY_MS, LAST_SEEN_REFRESH_MS, USER_SESSION_ENTITY_NAME, } from "./constants.js";
 import { userSessionEntity, userSessionTable } from "./schema/user-session.js";
 import { SESSION_REVOKED_AGGREGATE_TYPE, SESSION_REVOKED_EVENT_QN, sessionRevokedSchema, } from "./session-revoked-event.js";
-// Re-exported so existing `../sessions` importers keep working unchanged.
-export { isPrincipalBlocked };
 function settleLookup(lookup) {
     return lookup.then((value) => ({ ok: true, value }), () => ({ ok: false }));
 }

package/dist/shared/purge-files-reaching-subject.d.ts

@@ -7,6 +7,7 @@ export declare class FileSweepError extends Error {
     readonly entityName: string;
     constructor(code: Exclude<FileRefPurgeOutcome, "purged">, entityName: string);
 }
+export declare const PURGE_CANDIDATE_PAGE_SIZE = 200;
 export type DeleteFileBytes = (storageKey: string) => Promise<readonly string[]>;
 export type MissingStoragePolicy = {
     readonly mode: "fail";

package/dist/shared/purge-files-reaching-subject.js

@@ -70,6 +70,24 @@ function fieldsResolvingToSubject(fileEntity, row, rowTenantId, subjectKey) {
         }
     });
 }
+// A user owning many records must not load them all at once; the id cursor keeps each page
+// bounded while rows purged in place stay out of the way.
+export const PURGE_CANDIDATE_PAGE_SIZE = 200;
+async function* candidateRowsPaged(db, table, where) {
+    let cursor;
+    for (;;) {
+        const pageWhere = cursor === undefined ? where : { ...where, id: { gt: cursor } };
+        const page = await selectMany(db, table, pageWhere, {
+            orderBy: { col: "id", direction: "asc" },
+            limit: PURGE_CANDIDATE_PAGE_SIZE,
+        });
+        yield* page;
+        // skip: a short page is the last one
+        if (page.length < PURGE_CANDIDATE_PAGE_SIZE)
+            return;
+        cursor = page[page.length - 1]?.["id"];
+    }
+}
 const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
     entityName: "fileRef",
 });
@@ -99,8 +117,7 @@ export async function purgeFilesReachingSubject(args) {
     for (const fileEntity of fileEntities) {
         const seenRowIds = new Set();
         for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
-            const rows = await selectMany(db, fileEntity.table, where);
-            for (const row of rows) {
+            for await (const row of candidateRowsPaged(db, fileEntity.table, where)) {
                 const rowId = String(row["id"]);
                 const tenantId = parseTenantId(row["tenantId"]);
                 // skip: a row without a tenant cannot own tenant-scoped file refs

package/dist/shared/run-in-sub-transaction.js

@@ -1,9 +1,9 @@
 // Per-unit sub-transaction (one user, one purged row), nesting-aware across both db shapes:
-//   - top-level connection (postgres-js Sql) → `.begin` (BEGIN)
-//   - TransactionSql (inside the dispatcher's outer tx, where every
+//   - top-level connection (Bun.SQL pool) → `.begin` (BEGIN)
+//   - TransactionSQL (inside the dispatcher's outer tx, where every
 //     writeHandler already runs) → `.savepoint` (SAVEPOINT)
-// A TransactionSql has no `.begin`, so the previous unconditional `.begin`
-// threw "is not a function" on every user when invoked through the dispatcher
+// A transaction handle cannot begin another transaction, so the previous unconditional `.begin`
+// threw on every user when invoked through the dispatcher
 // (the cron path) → zero deletions in production, while direct-connection tests
 // stayed green. Selecting the available method makes the sub-tx work in both
 // contexts; on throw the savepoint rolls back just this user (others survive).
@@ -13,7 +13,7 @@ export async function runInSubTransaction(db, fn) {
     // without asRawClient (a test-only escape hatch).
     const runner = db;
     // savepoint-first: empirically (Bun 1.3.14, not re-checked on 1.4.0) the
-    // surfaces are NOT mutually exclusive — a TransactionSql exposes begin AND
+    // surfaces are NOT mutually exclusive — a TransactionSQL exposes begin AND
     // savepoint, only the top-level connection has begin alone. begin-first
     // picked the nested BEGIN inside a tx (the incident class above);
     // savepoint-first hits the savepoint there and falls back to begin top-level.

package/dist/step-dispatcher/deliver-dispatch-request.js

@@ -31,9 +31,16 @@ export async function eraseDispatchKey(aggregateId) {
         eraseReason: "step-dispatch-outcome-recorded",
     });
 }
-// Mail adapter failures carry no status to classify, so every one is retried.
+const SMTP_PERMANENT_REJECTION_MIN = 500;
+const SMTP_PERMANENT_REJECTION_MAX = 599;
+// Without an SMTP code the adapter gave nothing to classify, so the failure counts as transient.
 function mailResultAsDelivery(result) {
-    return result.ok ? result : { ...result, retryable: true };
+    if (result.ok)
+        return result;
+    const isPermanent = result.smtpCode !== undefined &&
+        result.smtpCode >= SMTP_PERMANENT_REJECTION_MIN &&
+        result.smtpCode <= SMTP_PERMANENT_REJECTION_MAX;
+    return { ok: false, error: result.error, retryable: !isPermanent };
 }
 // Outcome events are plaintext and generic; the request payload's per-dispatch
 // key is erased right after, so the PII dies with the dispatch instead of
@@ -137,7 +144,13 @@ async function sendDispatch(dispatchSpec, target) {
             aggregateId: target.aggregateId,
             errorName: err instanceof Error ? err.name : "unknown",
         });
-        return { ok: false, error: DISPATCH_THREW_ERROR, retryable: true };
+        // A mail adapter has no idempotency key: a throw after the provider accepted the message
+        // would send it again, so only the webhook (which carries one) is retried.
+        return {
+            ok: false,
+            error: DISPATCH_THREW_ERROR,
+            retryable: dispatchSpec.stepKind === "webhook.send",
+        };
     }
 }
 async function abortOnFinalAttempt(err, ctx, recorder, aggregateId, requestedPayload) {

package/dist/step-dispatcher/mail-runner.d.ts

@@ -12,6 +12,7 @@ export type MailDispatchResult = {
 } | {
     readonly ok: false;
     readonly error: string;
+    readonly smtpCode?: number;
 };
 export declare function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult>): void;
 export declare function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult>;

package/dist/tags/feature.js

@@ -30,6 +30,7 @@ import { TAGS_FEATURE_I18N } from "./i18n.js";
 import { createTagEditScreen, createTagListScreen } from "./screens.js";
 import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./web/constants.js";
 function registerTags(r, access, toggleable, ownership, parents) {
+    r.adoptsBundledLists();
     r.describe("Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: { reason } } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).");
     r.uiHints({
         displayLabel: "Tags",

package/dist/template-resolver/document-ops.d.ts

@@ -163,5 +163,10 @@ export type DocumentOpsResult = {
     readonly ok: false;
     readonly issues: FieldIssue[];
 };
+export declare const REPLACE_TEXT_ISSUE_CODES: {
+    readonly notFound: "text_not_found";
+    readonly spansFormatting: "text_spans_formatting";
+    readonly placeholderNotReplaceable: "placeholder_not_replaceable";
+};
 export declare function applyDocumentOps(input: DocumentOpsInput): DocumentOpsResult;
 export {};

package/dist/template-resolver/document-ops.js

@@ -283,14 +283,30 @@ function removeBlockOp(state, op, path) {
     found.entry.removed = true;
     return null;
 }
+export const REPLACE_TEXT_ISSUE_CODES = {
+    notFound: "text_not_found",
+    spansFormatting: "text_spans_formatting",
+    placeholderNotReplaceable: "placeholder_not_replaceable",
+};
+// document-blocks shows the line across formatting runs with placeholders as {{name}},
+// so a find that is visible there but lies in no single text node needs its own explanation.
+function textNotMatchedCode(block, find) {
+    if (!textLinesOf(block).some((line) => line.includes(find))) {
+        return REPLACE_TEXT_ISSUE_CODES.notFound;
+    }
+    return find.includes("{{")
+        ? REPLACE_TEXT_ISSUE_CODES.placeholderNotReplaceable
+        : REPLACE_TEXT_ISSUE_CODES.spansFormatting;
+}
 function replaceTextOp(state, op, path) {
     const found = lookupEntry(state, op.blockId, `${path}.blockId`);
     if ("issue" in found)
         return found.issue;
     const { entry } = found;
     const count = textNodesIn([entry.node]).reduce((sum, node) => sum + occurrencesOf(node.text ?? "", op.find), 0);
-    if (count === 0)
-        return patchIssue(`${path}.find`, "text_not_found", { find: op.find });
+    if (count === 0) {
+        return patchIssue(`${path}.find`, textNotMatchedCode(entry.node, op.find), { find: op.find });
+    }
     if (count > 1)
         return patchIssue(`${path}.find`, "text_ambiguous", { find: op.find, count });
     entry.node = replaceInContent([entry.node], op.find, op.replace)[0] ?? entry.node;

package/dist/template-resolver/feature.js

@@ -22,7 +22,7 @@ import { makeResourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.js"
 import { makeResourceRemoveWrite } from "./handlers/resource-remove.write.js";
 import { makeResourceUploadWrite } from "./handlers/resource-upload.write.js";
 import { makeSendTestWrite } from "./handlers/send-test.write.js";
-import { sendTestStatusQuery } from "./handlers/send-test-status.query.js";
+import { makeSendTestStatusQuery } from "./handlers/send-test-status.query.js";
 import { makeSetWrite } from "./handlers/set.write.js";
 import { tenantOverrideCountsQuery } from "./handlers/tenant-override-counts.query.js";
 import { tenantOverridesQuery } from "./handlers/tenant-overrides.query.js";
@@ -137,7 +137,7 @@ export function createTemplateResolverFeature(opts = {}) {
             preview: r.queryHandler(previewQuery),
             documentBlocks: r.queryHandler(documentBlocksQuery),
             exportBundle: r.queryHandler(exportBundleQuery),
-            sendTestStatus: r.queryHandler(sendTestStatusQuery),
+            sendTestStatus: r.queryHandler(makeSendTestStatusQuery(policy)),
         };
         for (const collection of collections) {
             r.contentCollection({

package/dist/template-resolver/handlers/layout-source.query.d.ts

@@ -28,4 +28,8 @@ export declare const layoutSourceQuery: import("@cosmicdrift/kumiko-types/define
     }>;
     slug: z.ZodDefault<z.ZodString>;
     locale: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
 }, z.core.$strip>, LayoutSourceResponse, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/layout-source.query.js

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { filterDeliveredTo } from "../api.js";
 import { readLayoutRegions } from "../layout-regions.js";
@@ -8,6 +9,7 @@ import { deliveryPolicyOf } from "../template-delivery-policy.js";
 import { draftViewerTenantId, isHiddenSystemDraft, toWorkingRow, } from "../template-draft.js";
 import { readMailLayoutMeta } from "../template-meta.js";
 import { FALLBACK_LOCALE } from "../web/constants.js";
+import { TemplateResolverErrors } from "../web/qualified-names.js";
 import { localeSchema, templateSlugSchema } from "./shared.js";
 import { parseStoredJson } from "./template-gates.js";
 const EMPTY_REGIONS = { header: "", signature: "", footer: "" };
@@ -31,8 +33,12 @@ function toSourceRow(row) {
 function layoutFormat(row) {
     return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
 }
-function pickEditedRows(rows, user, locale) {
-    const tenantRow = user.roles.includes("SystemAdmin")
+function pickEditedRows(rows, caller, scope, locale) {
+    // A SystemAdmin editing the tenant layout sees the system version like a tenant does: served only, no draft.
+    const user = scope === "system"
+        ? caller
+        : { ...caller, roles: caller.roles.filter((role) => role !== "SystemAdmin") };
+    const tenantRow = scope === "system"
         ? null
         : pickByLocale(rows.filter((row) => row.scope === "tenant"), locale);
     const systemRow = pickByLocale(rows.filter((row) => row.scope === "system" && !isHiddenSystemDraft(user, row)), locale);
@@ -73,15 +79,29 @@ export const layoutSourceQuery = defineQueryHandler({
         kind: z.enum(["mail-layout", "pdf-layout"]),
         slug: templateSlugSchema.default("default"),
         locale: localeSchema.optional(),
+        scope: z.enum(["tenant", "system"]).optional(),
     }),
     access: { roles: ["TenantAdmin", "SystemAdmin"] },
-    description: "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
+    description: "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version by default and also receives its mjml source; scope tenant loads the SystemAdmin's own tenant layout instead, and scope system is refused for everyone else. Use it to load the layout editor.",
     handler: async (query, ctx) => {
         const { kind, slug, locale } = query.payload;
-        const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+        const callerIsSystemAdmin = query.user.roles.includes("SystemAdmin");
+        const scope = query.payload.scope ?? (callerIsSystemAdmin ? "system" : "tenant");
+        if (scope === "system" && !callerIsSystemAdmin) {
+            throw new AccessDeniedError({
+                i18nKey: "errors.access.denied",
+                details: { reason: TemplateResolverErrors.systemAdminRequired },
+            });
+        }
         const policy = deliveryPolicyOf(ctx.registry);
         const rows = await filterDeliveredTo(ctx.db, policy, query.user, await selectMany(ctx.db, templateResourcesTable, { kind, slug }));
-        const { tenantRow, systemRow } = pickEditedRows(rows, query.user, locale);
-        return buildLayoutSource({ kind, locale, isSystemAdmin, tenantRow, systemRow });
+        const { tenantRow, systemRow } = pickEditedRows(rows, query.user, scope, locale);
+        return buildLayoutSource({
+            kind,
+            locale,
+            isSystemAdmin: scope === "system",
+            tenantRow,
+            systemRow,
+        });
     },
 });

package/dist/template-resolver/handlers/overview.query.js

@@ -1,10 +1,11 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
 import * as z from "zod";
 import { templateResourcesTable } from "../table.js";
 import { deliveryPolicyOf, isTenantOverrideServed, } from "../template-delivery-policy.js";
 import { activeSinceOf, activeVersionOf, draftViewerTenantId, isHiddenSystemDraft, isSystemAdmin, parseTemplateDraft, servedVersionOf, } from "../template-draft.js";
-import { mayEditTemplate } from "../template-edit-policy.js";
+import { mayEditTemplate, templateEditAccess, } from "../template-edit-policy.js";
 import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.js";
 import { collectTemplateUsage } from "../template-usage.js";
 import { DEFAULT_MAIL_LAYOUT_SLUG, FALLBACK_LOCALE, } from "../web/constants.js";
@@ -107,7 +108,9 @@ function splitDocumentSlug(slug) {
         ? { feature: "", notification: slug }
         : { feature: slug.slice(0, separator), notification: slug.slice(separator + 1) };
 }
-function compareBy(field, a, b) {
+function compareBy(field, a, b, shownTitle) {
+    if (field === "title")
+        return shownTitle(a).localeCompare(shownTitle(b));
     return String(a[field]).localeCompare(String(b[field]));
 }
 function isSortField(value) {
@@ -207,13 +210,15 @@ function withOverriddenBy(rows, overrides) {
         }
         : row);
 }
-function filterRows(rows, search, filters, layoutSlug) {
+function filterRows(rows, search, filters, layoutSlug, shownTitle) {
     const needle = search?.trim().toLowerCase() ?? "";
     return rows.filter((row) => {
         if (layoutSlug !== undefined && row.layoutSlug !== layoutSlug)
             return false;
-        if (needle !== "" && !`${row.title} ${row.slug}`.toLowerCase().includes(needle))
+        if (needle !== "" &&
+            !`${shownTitle(row)} ${row.title} ${row.slug}`.toLowerCase().includes(needle)) {
             return false;
+        }
         return filters.every((filter) => filter.value.includes(String(row[filter.field])));
     });
 }
@@ -235,7 +240,7 @@ export function makeOverviewQuery(policy) {
             offset: z.number().int().min(0).optional(),
             totalCount: z.boolean().optional(),
         }),
-        access: { roles: ["TenantAdmin", "SystemAdmin"] },
+        access: templateEditAccess(policy.tenantEditable),
         description: "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; templates of notifications registered with `systemOnly` are listed for SystemAdmins only, and a TenantAdmin sees only the templates the app lists in tenantEditable; a tenant override of a template that is not listed is not delivered, so the row shows the system version with `lockedOverride` true (SystemAdmin only); use it to browse and filter all templates at a glance.",
         handler: async (query, ctx) => {
             const payload = query.payload;
@@ -255,10 +260,13 @@ export function makeOverviewQuery(policy) {
             const overviewRows = isSystemAdmin(query.user)
                 ? withOverriddenBy(rowsWithUsage, tenantOverrideCountsResultSchema.parse(await ctx.query(TemplateResolverQueries.tenantOverrideCounts, {})))
                 : rowsWithUsage;
-            const filtered = filterRows(overviewRows, payload.search, payload.filters ?? [], payload.layoutSlug);
+            // A seeded title can be an i18n key; search and sort must see what the admin sees.
+            const i18n = createI18n(ctx.registry, { defaultLocale: "en" });
+            const shownTitle = (row) => i18n.t(row.title, ctx.locale);
+            const filtered = filterRows(overviewRows, payload.search, payload.filters ?? [], payload.layoutSlug, shownTitle);
             const sortField = payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";
             const direction = (payload.sortDirection ?? "desc") === "desc" ? -1 : 1;
-            filtered.sort((a, b) => direction * compareBy(sortField, a, b) || a.id.localeCompare(b.id));
+            filtered.sort((a, b) => direction * compareBy(sortField, a, b, shownTitle) || a.id.localeCompare(b.id));
             const offset = payload.offset ?? 0;
             return {
                 rows: filtered.slice(offset, offset + payload.limit),

package/dist/template-resolver/handlers/patch-draft.write.js

@@ -27,7 +27,7 @@ export function makePatchDraftWrite(policy) {
             ops: documentOpsSchema,
         }),
         access: templateEditAccess(policy.tenantEditable),
-        description: "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. A TenantAdmin may patch only templates the app lists in tenantEditable, otherwise SystemAdmin only. Returns the written row.",
+        description: "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once within one formatting run and cannot contain a {{placeholder}}: a find across a formatting change fails with text_spans_formatting, a find with a placeholder with placeholder_not_replaceable, and the formatting of the replaced text is kept), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. A TenantAdmin may patch only templates the app lists in tenantEditable, otherwise SystemAdmin only. Returns the written row.",
         handler: async (event, ctx) => {
             const { slug, kind, locale, base, ops } = event.payload;
             const refused = refuseTemplateEdit(policy, event.user, { slug, kind });