@cosmicdrift/kumiko-samples 0.388.0 → 0.389.0

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -1,6 +1,13 @@
 // Public API of the document-ingest-foundation bundled-feature.
 
 export { documentIngestAggregateId } from "./aggregate-id.ts";
+export {
+  type AppendMissingExtractEventDeps,
+  type AppendMissingExtractEventOptions,
+  type AppendMissingExtractEventResult,
+  appendMissingDocumentExtractEvent,
+  type ExistingDocumentExtract,
+} from "./append-missing-extract-event.ts";
 export {
   type DocumentExtractMeta,
   documentExtractEntity,
@@ -14,8 +21,12 @@ export {
   DOCUMENT_INGEST_REQUESTED_EVENT_SHORT,
   DOCUMENT_INGEST_SKIPPED_EVENT_QN,
   DOCUMENT_INGEST_SKIPPED_EVENT_SHORT,
+  type DocumentExtractFailedPayload,
+  type DocumentExtractReadyPayload,
   type DocumentIngestRequestedPayload,
   type DocumentIngestSkippedPayload,
+  documentExtractFailedPayloadSchema,
+  documentExtractReadyPayloadSchema,
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events.ts";

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

@@ -44,6 +44,7 @@ export function createFeatureTogglesFeature(
   options: FeatureTogglesOptions = {},
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
+    r.adoptsBundledLists();
     r.describe(
       'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "shared"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );

package/packages/bundled-features/src/host-routing/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Redirects from /api paths fail at boot",
+    "detail": "Redirects run inside hostDispatch after static files and API routes, so a from of /api or /api/... was silently dead config. Boot validation now throws; the options and README already describe the HTML-fallback scope."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/host-routing/validate-options.ts

@@ -16,6 +16,11 @@ function validateRedirects(options: HostRoutingOptions): void {
     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/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -103,6 +103,7 @@ 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.",
       );

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

@@ -65,6 +65,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     );
   }
   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`.",
     );

package/packages/bundled-features/src/ledger/web/index.ts

@@ -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/packages/bundled-features/src/legal-pages/seed.ts

@@ -42,12 +42,15 @@ async function loadBlocksFromJson(path: string): Promise<readonly LegalContentBl
 
 // 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: LegalContentSeedSource): LegalContentSeedFn {
+export function legalContentSeed(
+  source: LegalContentSeedSource,
+  options?: { readonly folder?: string },
+): LegalContentSeedFn {
   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/packages/bundled-features/src/mail-transport-smtp/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "SMTP authentication is optional",
+    "detail": "authUser is no longer a required key and the SMTP password secret no longer counts as missing in readiness. With an empty user the transport connects without auth, which suits internal relays; with a user set, a missing password still fails the send."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/mail-transport-smtp/config-keys.ts

@@ -6,6 +6,7 @@ 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,
@@ -41,7 +42,6 @@ export const SMTP_CONFIG_KEYS = {
     },
   }),
   authUser: createTenantConfig("text", {
-    required: true,
     default: "",
     write: tenantAdminWrite,
     read: tenantAdminRead,

package/packages/bundled-features/src/mail-transport-smtp/feature.ts

@@ -105,8 +105,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 });
@@ -191,14 +190,13 @@ async function buildSmtpTransport(
     "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: MailConnectTarget;
   try {
@@ -227,7 +225,7 @@ async function buildSmtpTransport(
     port,
     secure,
     from,
-    auth: { user: authUser, pass: password },
+    ...(auth && { auth }),
     ...(target.servername && { servername: target.servername }),
   });
 }

package/packages/bundled-features/src/managed-pages/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "MANAGED_PAGES_FEATURE names the feature",
+    "detail": "The barrel exports the MANAGED_PAGES_FEATURE constant so other code can refer to the feature name without a string literal."
+  },
   {
     "version": "0.363.0",
     "type": "improvement",

package/packages/bundled-features/src/managed-pages/constants.ts

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

package/packages/bundled-features/src/managed-pages/feature.ts

@@ -10,6 +10,7 @@ import {
 } from "../page-render/index.ts";
 import { rateLimitedTextResponse, type SystemQueryFn } from "../shared/index.ts";
 import { BRANDING_KEYS, BRANDING_QUERY_QN, CUSTOM_CSS_KEY, coerceBranding } from "./branding.ts";
+import { MANAGED_PAGES_FEATURE } from "./constants.ts";
 import { createBrandingQuery } from "./handlers/branding.query.ts";
 import { bySlugQuery } from "./handlers/by-slug.query.ts";
 import { byTenantPublishedQuery } from "./handlers/by-tenant-published.query.ts";
@@ -153,7 +154,8 @@ export function createManagedPagesFeature(opts: ManagedPagesOptions): FeatureDef
   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.",
     );

package/packages/bundled-features/src/managed-pages/index.ts

@@ -21,6 +21,7 @@ export {
 // (`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.ts";
+export { MANAGED_PAGES_FEATURE } from "./constants.ts";
 export { createManagedPagesCssFeature } from "./css-gate.ts";
 export {
   createManagedPagesFeature,

package/packages/bundled-features/src/notes-history/handlers/add-note.write.ts

@@ -69,7 +69,7 @@ export function createAddNoteHandler(
       let authorName: string | null = 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/packages/bundled-features/src/personal-access-tokens/feature.ts

@@ -101,6 +101,7 @@ export function createPersonalAccessTokensFeature(
 ): FeatureDefinition {
   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.",
     );

package/packages/bundled-features/src/secrets/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Feature-prefixed undeclared secret keys are not deletable",
+    "detail": "The delete handler still accepts legacy undeclared keys, but a key starting with \"<feature>:\" of a mounted feature now fails as unknown key. Feature-owned credentials keep their writeRoles protection."
+  },
   {
     "version": "0.370.0",
     "type": "improvement",

package/packages/bundled-features/src/secrets/write-gate.ts

@@ -28,6 +28,11 @@ function unknownKeyFailure(key: string): SecretKeyWriteCheck {
   };
 }
 
+function isUnderMountedFeaturePrefix(registry: Registry, key: string): boolean {
+  const separator = key.indexOf(":");
+  return separator > 0 && registry.getFeature(key.slice(0, separator)) !== undefined;
+}
+
 function namespaceAcceptsKey(namespace: SecretNamespaceDefinition, key: string): boolean {
   const suffix = key.slice(namespace.qualifiedPrefix.length);
   if (suffix.length === 0) return false;
@@ -38,7 +43,9 @@ function namespaceAcceptsKey(namespace: SecretNamespaceDefinition, key: string):
 // 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: Registry,
   userRoles: readonly string[],
@@ -50,7 +57,7 @@ export function checkSecretKeyWrite(
   if (
     !keyDef &&
     !(namespace && namespaceAcceptsKey(namespace, key)) &&
-    options.allowUndeclared !== true
+    (options.allowUndeclared !== true || isUnderMountedFeaturePrefix(registry, key))
   ) {
     return unknownKeyFailure(key);
   }

package/packages/bundled-features/src/sessions/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "isPrincipalBlocked is no longer exported from sessions",
+    "detail": "The sessions export dropped its re-export of isPrincipalBlocked, which ignored isDeleted. isPrincipalRowBlocked from the user export covers status and isDeleted and is what the session callbacks use.",
+    "migration": "import isPrincipalRowBlocked (for a user row) or isPrincipalBlocked (for a bare status) from \"@cosmicdrift/kumiko-bundled-features/user\" instead of the sessions export"
+  },
   {
     "version": "0.384.0",
     "type": "improvement",

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

@@ -102,6 +102,7 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     "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.",
       );

package/packages/bundled-features/src/sessions/index.ts

@@ -15,7 +15,7 @@ export type {
   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,

package/packages/bundled-features/src/sessions/session-callbacks.ts

@@ -18,12 +18,7 @@ import { generateId, parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { encryptForDirectWrite } from "../shared/index.ts";
 import { tenantMembershipsTable } from "../tenant/index.ts";
-import {
-  isPrincipalBlocked,
-  isPrincipalRowBlocked,
-  type UserStatus,
-  userTable,
-} from "../user/index.ts";
+import { isPrincipalRowBlocked, type UserStatus, userTable } from "../user/index.ts";
 import {
   DEFAULT_SESSION_EXPIRY_MS,
   LAST_SEEN_REFRESH_MS,
@@ -36,9 +31,6 @@ import {
   sessionRevokedSchema,
 } from "./session-revoked-event.ts";
 
-// Re-exported so existing `../sessions` importers keep working unchanged.
-export { isPrincipalBlocked };
-
 type SettledLookup<T> = { readonly ok: true; readonly value: T } | { readonly ok: false };
 
 function settleLookup<T>(lookup: Promise<T>): Promise<SettledLookup<T>> {

package/packages/bundled-features/src/shared/purge-files-reaching-subject.ts

@@ -112,6 +112,29 @@ function fieldsResolvingToSubject(
   });
 }
 
+// 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: DbRunner,
+  table: FileEntity["table"],
+  where: WhereObject,
+): AsyncGenerator<Record<string, unknown>> {
+  let cursor: unknown;
+  for (;;) {
+    const pageWhere: WhereObject = cursor === undefined ? where : { ...where, id: { gt: cursor } };
+    const page = await selectMany<Record<string, unknown>>(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",
 });
@@ -165,8 +188,7 @@ export async function purgeFilesReachingSubject(args: {
   for (const fileEntity of fileEntities) {
     const seenRowIds = new Set<string>();
     for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
-      const rows = await selectMany<Record<string, unknown>>(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/packages/bundled-features/src/shared/run-in-sub-transaction.ts

@@ -1,11 +1,11 @@
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
 // 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).
@@ -21,7 +21,7 @@ export async function runInSubTransaction<T>(
     savepoint?: (f: (tx: DbRunner) => Promise<T>) => Promise<T>;
   };
   // 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/packages/bundled-features/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Mail steps do not retry permanent rejections or throws",
+    "detail": "MailDispatchResult failures take an optional smtpCode; 5xx is permanent and recorded after the first attempt. A throwing mail runner is not retried, since the message may already be sent. A mail runner that wants a retry after a transport error should return a failure without smtpCode instead of throwing."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/step-dispatcher/deliver-dispatch-request.ts

@@ -54,9 +54,17 @@ type DeliveryResult =
   | { readonly ok: true; readonly status: number }
   | { readonly ok: false; readonly error: string; readonly retryable: boolean };
 
-// 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: MailDispatchResult): DeliveryResult {
-  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 };
 }
 
 export type DeliverDispatchRequestArgs = {
@@ -205,7 +213,13 @@ async function sendDispatch(
       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",
+    };
   }
 }
 

package/packages/bundled-features/src/step-dispatcher/mail-runner.ts

@@ -15,7 +15,8 @@ export type MailSpec = z.infer<typeof mailSpecSchema>;
 
 export type MailDispatchResult =
   | { readonly ok: true; readonly status: number }
-  | { readonly ok: false; readonly error: string };
+  // smtpCode is the adapter's SMTP reply code; a 5xx is a permanent rejection and is not retried.
+  | { readonly ok: false; readonly error: string; readonly smtpCode?: number };
 
 let mailRunner: (spec: MailSpec) => Promise<MailDispatchResult> = async () => ({
   ok: false,

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

@@ -54,6 +54,7 @@ function registerTags(
   ownership: EntityDefinition["access"] | undefined,
   parents: readonly string[] | undefined,
 ): void {
+  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).",
   );

package/packages/bundled-features/src/template-resolver/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "copy-locale reads source files from the owning tenant's storage",
+    "detail": "The copy of linked files uses readFileRefContent with the provider of the fileRef's tenant. A source file whose fileRef row exists but whose bytes cannot be read fails the copy with template_resource_source_unreadable and releases the files already copied. A deleted fileRef is still left out of the copy."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "replaceText explains finds across formatting or placeholders",
+    "detail": "replaceText matches inside single text nodes so formatting stays intact. A find that appears in the block line but crosses a formatting change now fails with text_spans_formatting, and a find with a {{placeholder}} fails with placeholder_not_replaceable, both with translated messages. Only a string that is not in the block at all still gives text_not_found."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "send-test-status follows the tenantEditable roles",
+    "detail": "send-test-status takes its access from templateEditAccess(policy.tenantEditable), like send-test. Roles that may send a test mail now get the status, and a TenantAdmin without an edit opt-in gets a 403 on both."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "overview follows the tenantEditable roles",
+    "detail": "The overview query takes its access from templateEditAccess(policy.tenantEditable). An opted-in role lists exactly the released templates, and a TenantAdmin without an opt-in is refused with a 403, matching the screen visibility and the write handlers."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "overview search and sort use the translated title",
+    "detail": "The overview query translates a seeded titleI18nKey with the request locale before it filters by search and sorts by title. A search for the visible title now matches, and the raw key is still searchable."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "legalContentSeed keeps and can set the content folder",
+    "detail": "seedTextBlock no longer resets the folder of an existing block to null when the seed passes no folder. legalContentSeed takes an optional folder, so apps do not need their own seed loop to keep legal blocks in the SystemAdmin content tree."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/template-resolver/document-ops.ts

@@ -389,6 +389,23 @@ function removeBlockOp(
   return null;
 }
 
+export const REPLACE_TEXT_ISSUE_CODES = {
+  notFound: "text_not_found",
+  spansFormatting: "text_spans_formatting",
+  placeholderNotReplaceable: "placeholder_not_replaceable",
+} as const;
+
+// 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: JSONContent, find: string): string {
+  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: OpState,
   op: Extract<DocumentOp, { op: "replaceText" }>,
@@ -401,7 +418,9 @@ function replaceTextOp(
     (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;
   return null;

package/packages/bundled-features/src/template-resolver/feature.ts

@@ -29,7 +29,7 @@ import { makeResourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.ts"
 import { makeResourceRemoveWrite } from "./handlers/resource-remove.write.ts";
 import { makeResourceUploadWrite } from "./handlers/resource-upload.write.ts";
 import { makeSendTestWrite } from "./handlers/send-test.write.ts";
-import { sendTestStatusQuery } from "./handlers/send-test-status.query.ts";
+import { makeSendTestStatusQuery } from "./handlers/send-test-status.query.ts";
 import { makeSetWrite } from "./handlers/set.write.ts";
 import { tenantOverrideCountsQuery } from "./handlers/tenant-override-counts.query.ts";
 import { tenantOverridesQuery } from "./handlers/tenant-overrides.query.ts";
@@ -191,7 +191,7 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       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) {