@cosmicdrift/kumiko-samples 0.365.1 → 0.367.0

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

@@ -6,8 +6,12 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { Element as ScanElement } from "happy-dom";
 import * as z from "zod";
-import { withParsedDocument } from "./document-sanitizer.js";
-import { isDocumentPlaceholderHref, isDocumentReferenceName } from "./document-schema.js";
+import { conditionScopeElement, withParsedDocument } from "./document-sanitizer.js";
+import {
+  DOCUMENT_CONDITION_ATTRIBUTE,
+  isDocumentPlaceholderHref,
+  isDocumentReferenceName,
+} from "./document-schema.js";
 import type { TemplateMeta } from "./template-meta.js";
 
 export const SYSTEM_PLACEHOLDERS: ReadonlySet<string> = new Set([
@@ -56,6 +60,7 @@ const scalarVariableSchema = z.discriminatedUnion("type", [
       .optional(),
   }),
   z.object({ ...variableCommon, type: z.literal("date"), example: textLikeExample }),
+  z.object({ ...variableCommon, type: z.literal("percent"), example: z.number().optional() }),
 ]);
 
 const variableDefSchema = z.union([
@@ -154,30 +159,49 @@ const NAME_ATTRIBUTE_BY_TAG: Readonly<Record<string, string>> = {
   div: "data-steps",
 };
 
+function scanRepeatRows(root: ScanElement, scope: PlaceholderScope): void {
+  for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+    const listName = element.getAttribute("data-each") ?? "";
+    const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
+    if (def?.type === "list") scope.used.add(listName);
+    else scope.unknown.add(listName);
+  }
+}
+
+function scanConditions(root: ScanElement, scope: PlaceholderScope): void {
+  for (const element of Array.from(root.querySelectorAll(`[${DOCUMENT_CONDITION_ATTRIBUTE}]`))) {
+    const itemFields = listItemFields(
+      scope.variables,
+      enclosingEachName(conditionScopeElement(element)),
+    );
+    recordName(element.getAttribute(DOCUMENT_CONDITION_ATTRIBUTE) ?? "", itemFields, scope);
+  }
+}
+
+function scanReferences(root: ScanElement, scope: PlaceholderScope): void {
+  for (const element of Array.from(
+    root.querySelectorAll("span[data-variable], div[data-steps], a[href], img[data-resource]"),
+  )) {
+    const itemFields = listItemFields(scope.variables, enclosingEachName(element));
+    const tag = element.tagName.toLowerCase();
+    const nameAttribute = NAME_ATTRIBUTE_BY_TAG[tag];
+    if (nameAttribute !== undefined) {
+      recordName(element.getAttribute(nameAttribute) ?? "", itemFields, scope);
+    } else if (tag === "a") {
+      const href = element.getAttribute("href") ?? "";
+      if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
+    } else {
+      const key = element.getAttribute("data-resource") ?? "";
+      if (!scope.resourceKeys.has(key)) scope.unknownResources.add(key);
+    }
+  }
+}
+
 function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
   withParsedDocument(body, (root) => {
-    for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
-      const listName = element.getAttribute("data-each") ?? "";
-      const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
-      if (def?.type === "list") scope.used.add(listName);
-      else scope.unknown.add(listName);
-    }
-    for (const element of Array.from(
-      root.querySelectorAll("span[data-variable], div[data-steps], a[href], img[data-resource]"),
-    )) {
-      const itemFields = listItemFields(scope.variables, enclosingEachName(element));
-      const tag = element.tagName.toLowerCase();
-      const nameAttribute = NAME_ATTRIBUTE_BY_TAG[tag];
-      if (nameAttribute !== undefined) {
-        recordName(element.getAttribute(nameAttribute) ?? "", itemFields, scope);
-      } else if (tag === "a") {
-        const href = element.getAttribute("href") ?? "";
-        if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
-      } else {
-        const key = element.getAttribute("data-resource") ?? "";
-        if (!scope.resourceKeys.has(key)) scope.unknownResources.add(key);
-      }
-    }
+    scanRepeatRows(root, scope);
+    scanConditions(root, scope);
+    scanReferences(root, scope);
   });
 }
 

package/packages/bundled-features/src/template-resolver/web/i18n.ts

@@ -96,6 +96,8 @@ export const defaultTranslations: TranslationsByLocale = {
       "“{detail}” templates are written through their own editor, not through a collection.",
     "templateResolver.errors.noSystemTemplate": "There is no active system template to reset to.",
     "templateResolver.errors.noDraft": "There is no draft to discard.",
+    "templateResolver.errors.systemOnlyTemplate":
+      "Only the platform maintains this template; it cannot be overridden per tenant.",
     "templateResolver.errors.template.invalidMeta": "The template settings are invalid.",
     "templateResolver.errors.template.meta.subject.required": "The subject is missing.",
     "templateResolver.errors.template.meta.subject.invalid":

package/packages/bundled-features/src/template-resolver-user-data/index.ts

@@ -16,7 +16,7 @@ export const templateResolverUserDataFeature = defineFeature("template-resolver-
   // template-resolver is optional for the same reason as in
   // notes-history-user-data: a toggleable mount would otherwise trip the
   // "effectively disabled" boot warning even though the entity is there.
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   r.optionalRequires("template-resolver");
   r.useExtension(EXT_USER_DATA, "user-content-entry", {
     export: userContentExportHook,

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

@@ -80,7 +80,7 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
       recommended: true,
     });
     r.systemScope();
-    r.requires("config");
+    r.requires({ features: ["config"] });
     r.extendsRegistrar(EXT_ASSIGNABLE_ROLE, {});
     // The elevation guards read the registry, the screens only these options: a role the
     // server accepts but the screen omits is silently stripped on the next member-roles save.
@@ -92,9 +92,9 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
         );
       }
     });
-    r.entity("tenant", tenantEntity);
-    r.entity("tenant-membership", tenantMembershipEntity);
-    r.entity("tenant-invitation", tenantInvitationEntity);
+    r.entity({ name: "tenant", ...tenantEntity });
+    r.entity({ name: "tenant-membership", ...tenantMembershipEntity });
+    r.entity({ name: "tenant-invitation", ...tenantInvitationEntity });
 
     r.config({
       keys: {

package/packages/bundled-features/src/tenant/seeding.ts

@@ -292,7 +292,7 @@ export async function seedTenant(
 
   // "tenant:seed" matches no handler-scoped hook, only entity-scoped ones
   // (keyed by result.entityName === "tenant") — that's exactly what
-  // tier-engine's `r.hook("postSave", { allOf: "tenant" }, ...)` needs.
+  // tier-engine's `r.hook({ type: "postSave", target: { allOf: "tenant" }, ... })` needs.
   await fireEntityPostSave(hooks, "tenant:seed", result.data, { tenantId: options.id, db });
 
   return { id: options.id };

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -63,7 +63,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
       category: "compliance",
       recommended: false,
     });
-    r.requires("tenant", "compliance-profiles");
+    r.requires({ features: ["tenant", "compliance-profiles"] });
     r.optionalRequires("sessions");
     r.usesApi("compliance.forTenant");
 
@@ -140,8 +140,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
         if (!ctx.registry) {
           throw new Error("run-tenant-destruction: ctx.registry required (JobContext incomplete)");
         }
-        const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-        const now = T.Now.instant();
+        const now = ctx.tz.now();
         // Without crossTenantReads (undeclared hatch) fall through to the sweep.
         if (ctx.crossTenantReads && !(await hasTenantDestructionWork(ctx.crossTenantReads, now))) {
           // skip: no tenant is due, so the sweep would not touch anything

package/packages/bundled-features/src/tenant-settings/feature.ts

@@ -22,7 +22,7 @@ export function createTenantSettingsFeature(
   opts: TenantSettingsFeatureOptions = {},
 ): FeatureDefinition {
   return defineFeature(TENANT_SETTINGS_FEATURE_NAME, (r) => {
-    r.requires("config");
+    r.requires({ features: ["config"] });
     r.describe(
       "Per-tenant Currency + Locale defaults, exposed as two config keys (tenant-settings:config:currency, tenant-settings:config:locale) that surface in the self-populating Settings-Hub via `mask`. Pair with defineCreateWithTenantDefaults to auto-fill a money field's currency or a locale field on create instead of hard-coding a literal per entity.",
     );

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -206,10 +206,10 @@ export function createTierEngineFeature<
       category: "billing",
       recommended: false,
     });
-    r.requires("config");
-    r.requires("tenant");
+    r.requires({ features: ["config"] });
+    r.requires({ features: ["tenant"] });
 
-    r.entity("tier-assignment", tierAssignmentEntity);
+    r.entity({ name: "tier-assignment", ...tierAssignmentEntity });
 
     // Standard-CRUD via Helper.
     r.writeHandler(
@@ -369,25 +369,33 @@ export function createTierEngineFeature<
     onTierAssigned.fn = applyAssignment;
 
     // Invalidation: tier-assignment CRUD events (e.g. the billing webhook) update the cache.
-    r.hook("postSave", { allOf: "tier-assignment" }, async (result) => {
-      // result.data has tenantId + tier (after entity-update merge)
-      const data = result.data as { tenantId?: unknown; tier?: unknown }; // @cast-boundary engine-payload
-      // skip: defensive type-guard auf payload-shape. Bei korrekt gerenderten
-      // entity-events sind beide fields immer strings; ein malformed-payload
-      // (custom-handler-bug) würde hier silent zum cache-skip führen statt
-      // throwing — der lifecycle-pipeline darf nicht durch hook-fehler
-      // blocken (afterCommit-pattern, side-effect-best-effort).
-      if (typeof data.tenantId !== "string" || typeof data.tier !== "string") return;
-      applyAssignment(data.tenantId as TenantId, data.tier);
+    r.hook({
+      type: "postSave",
+      target: { allOf: "tier-assignment" },
+      handler: async (result) => {
+        // result.data has tenantId + tier (after entity-update merge)
+        const data = result.data as { tenantId?: unknown; tier?: unknown }; // @cast-boundary engine-payload
+        // skip: defensive guard on the payload shape. Correct entity events
+        // always carry both fields as strings; a malformed payload (a custom
+        // handler bug) skips the cache update instead of throwing, because a
+        // hook error must not block the lifecycle pipeline (afterCommit,
+        // best-effort side effect).
+        if (typeof data.tenantId !== "string" || typeof data.tier !== "string") return;
+        applyAssignment(data.tenantId as TenantId, data.tier);
+      },
     });
-    r.hook("postDelete", { allOf: "tier-assignment" }, async (payload) => {
-      const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
-      // skip: gleiche type-guard semantik wie postSave-hook oben.
-      if (typeof data.tenantId !== "string") return;
-      const tenantId = data.tenantId as TenantId;
-      takeTicket(tenantId);
-      cache.delete(tenantId);
-      publishAssignmentChange(tenantId);
+    r.hook({
+      type: "postDelete",
+      target: { allOf: "tier-assignment" },
+      handler: async (payload) => {
+        const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
+        // skip: gleiche type-guard semantik wie postSave-hook oben.
+        if (typeof data.tenantId !== "string") return;
+        const tenantId = data.tenantId as TenantId;
+        takeTicket(tenantId);
+        cache.delete(tenantId);
+        publishAssignmentChange(tenantId);
+      },
     });
 
     // Auto-default-tier-on-tenant-signup: hook fires inTransaction (atomic
@@ -406,10 +414,10 @@ export function createTierEngineFeature<
       const defaultTier = opts.defaultTier;
       const autoDefaultTierHookReason =
         "seeds the default tier-assignment stream of the tenant just created";
-      r.hook(
-        "postSave",
-        { allOf: "tenant" },
-        async (result, ctx) => {
+      r.hook({
+        type: "postSave",
+        target: { allOf: "tenant" },
+        handler: async (result, ctx) => {
           // result-shape: kumiko-framework's SaveContext mit isNew + data
           const saveResult = result as { isNew?: unknown; data?: unknown }; // @cast-boundary engine-payload
           // skip: nur bei tenant-create (initial) — tenant-updates feuern
@@ -462,8 +470,9 @@ export function createTierEngineFeature<
             tdb,
           );
         },
-        { phase: HookPhases.inTransaction, escapeHatch: { reason: autoDefaultTierHookReason } },
-      );
+        phase: HookPhases.inTransaction,
+        escapeHatch: { reason: autoDefaultTierHookReason },
+      });
     }
 
     // Extension-point declaration + self-registration. Pattern analog

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

@@ -28,7 +28,7 @@ export function createUserFeature(): FeatureDefinition {
       recommended: true,
     });
     r.systemScope();
-    r.entity("user", userEntity);
+    r.entity({ name: "user", ...userEntity });
 
     // Self-extension: `user` declares AND fulfils principalStatus (precedent:
     // tier-engine/feature.ts) — wires the blocked-principal check into every stack that mounts `user`.

package/packages/bundled-features/src/user-data-rights/README.md

@@ -14,7 +14,7 @@ an. user-data-rights orchestriert Export- und Forget-Pipeline:
 
 ```ts
 defineFeature("tasks", (r) => {
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   r.useExtension(EXT_USER_DATA, "task", {
     export: async (ctx) => ({
       entity: "task",

package/packages/bundled-features/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "Tests seed tenant memberships and events through the framework",
+    "detail": "Test-only change. Integration tests create read_tenant_memberships from tenantMembershipEntity and seed rows with seedRow instead of hand-written DDL and raw INSERTs. Fake events go through the event-store append, and backdated audit events are written with runSeedWritesAt instead of an UPDATE on created_at. No runtime behavior changes."
+  },
   {
     "version": "0.365.0",
     "type": "improvement",

package/packages/bundled-features/src/user-data-rights/feature.ts

@@ -197,7 +197,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       category: "compliance",
       recommended: false,
     });
-    r.requires("user", "data-retention", "compliance-profiles", "sessions");
+    r.requires({ features: ["user", "data-retention", "compliance-profiles", "sessions"] });
     r.usesApi("compliance.forTenant");
     r.usesApi("retention.policyFor");
     // S2.U6 — restrict-account ruft sessions.revokeAllForUser cross-feature.
@@ -242,15 +242,15 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
     );
 
     // S2.U3 Atom 1b — ExportJob-Lifecycle-Entity.
-    r.entity("export-job", exportJobEntity);
+    r.entity({ name: "export-job", ...exportJobEntity });
 
     // S2.U3 Atom 4a — Download-Token-Entity. Worker generiert Token beim
     // Flip auf done (siehe run-export-jobs.ts). Hash in DB, plain im
     // RunExportJobsResult fuer Atom 5 (Notification per Email).
-    r.entity("export-download-token", exportDownloadTokenEntity);
+    r.entity({ name: "export-download-token", ...exportDownloadTokenEntity });
 
     // S2.U7 — Audit-Trail invalid Download-Attempts (DPO Brute-Force-Detection).
-    r.entity("download-attempt", downloadAttemptEntity);
+    r.entity({ name: "download-attempt", ...downloadAttemptEntity });
 
     // S2.U6 — DSGVO Art. 18 Account-Freeze (Verarbeitungs-Pause).
     // Endpoints fuer Restrict + Lift. Login-Block fuer Restricted Users

package/packages/bundled-features/src/user-data-rights-defaults/feature.ts

@@ -40,7 +40,7 @@ import {
 // `user` (S2.H1) und `fileRef` (S2.H2).
 //
 // Architektur-Entscheidung (S2.H1+H2): user-data-rights selbst kann
-// nicht r.requires("user", "files") + r.useExtension(EXT_USER_DATA, ...)
+// nicht r.requires({ features: ["user", "files"] }) + r.useExtension(EXT_USER_DATA, ...)
 // machen weil es selbst Provider von EXT_USER_DATA ist (Boot-Validator
 // lehnt self-extension ab). Lösung: drittes optional-mountbares Feature
 // das requires beide Sources + die useExtension-Calls macht.
@@ -68,7 +68,7 @@ export function createUserDataRightsDefaultsFeature(): FeatureDefinition {
       category: "compliance",
       recommended: false,
     });
-    r.requires("user", "files", "user-data-rights");
+    r.requires({ features: ["user", "files", "user-data-rights"] });
     // Optional sources: hooks are registered unconditionally but each one
     // no-ops at runtime when its source feature isn't mounted (see
     // hooks/feature-mounted.ts) — the export runner has no per-hook

package/packages/bundled-features/src/user-profile/feature.ts

@@ -41,10 +41,10 @@ export function createUserProfileFeature(options?: UserProfileFeatureOptions): F
       category: "identity",
       recommended: true,
     });
-    r.requires("user");
-    r.requires("auth-email-password");
-    r.requires("user-data-rights");
-    r.requires("user-data-rights-defaults");
+    r.requires({ features: ["user"] });
+    r.requires({ features: ["auth-email-password"] });
+    r.requires({ features: ["user-data-rights"] });
+    r.requires({ features: ["user-data-rights-defaults"] });
 
     const handlers = allowEmailChange ? { changeEmail: r.writeHandler(changeEmailWrite) } : {};
 

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

@@ -30,7 +30,7 @@ export function createWaitlistFeature(opts: WaitlistOptions = {}): FeatureDefini
     );
     r.uiHints({ displayLabel: "Waitlist", category: "data", recommended: false });
     r.systemScope();
-    r.requires("tenant", "auth-email-password", "user-data-rights");
+    r.requires({ features: ["tenant", "auth-email-password", "user-data-rights"] });
     r.translations({ keys: WAITLIST_I18N });
 
     r.notification("confirmation", {
@@ -43,7 +43,7 @@ export function createWaitlistFeature(opts: WaitlistOptions = {}): FeatureDefini
       localizedTemplate: waitlistAdminNoticeTemplate,
     });
 
-    r.entity("waitlistEntry", waitlistEntryEntity);
+    r.entity({ name: "waitlistEntry", ...waitlistEntryEntity });
     r.writeHandler(createSubmitHandler(opts));
     r.writeHandler(createInviteHandler(opts.invite));
     r.writeHandler(rejectHandler);

package/samples/apps/cap-billing-demo/README.md

@@ -102,7 +102,7 @@ In the browser, use the Designer/Admin UI to set the config key
 there's no HTTP endpoint for it because the sample shows the
 architecture, not an inbox UI.
 
-If you want clickable: write a small `r.queryHandler("inbox:list")`
+If you want clickable: write a small `r.queryHandler({ name: "inbox:list", … })`
 that returns `getInbox(ctx.user.tenantId)`. ~20 LOC, deliberately
 omitted to keep the focus on cap+tier.
 

package/samples/apps/cap-billing-demo/src/feature.ts

@@ -183,10 +183,10 @@ export const newsletterFeature = defineFeature(FEATURE_NAME, (r) => {
   // Hard-deps: mail-foundation für Plugin-API + config für tier-Wahl +
   // cap-counter (transitiv via withCapEnforcement, aber explicit ist
   // klarer für boot-Validator-Errors).
-  r.requires("config");
-  r.requires("cap-counter");
-  r.requires(mailFoundationFeature.name);
-  r.requires(BILLING_FOUNDATION_FEATURE);
+  r.requires({ features: ["config"] });
+  r.requires({ features: ["cap-counter"] });
+  r.requires({ features: [mailFoundationFeature.name] });
+  r.requires({ features: [BILLING_FOUNDATION_FEATURE] });
 
   // Tier-config-key. Tenant-Admin setzt's; default "free".
   r.config(

package/samples/apps/cap-billing-demo/src/run-config.ts

@@ -1,7 +1,7 @@
 // Single source of truth für die Feature-Komposition der Demo-App.
 //
 // **Mount-Order matters:** mail-foundation MUSS vor mail-transport-
-// inmemory stehen (`r.requires("mail-foundation")` im Plugin); das
+// inmemory stehen (`r.requires({ features: ["mail-foundation"] })` im Plugin); das
 // newsletter-feature kommt danach (es nutzt mail-foundation +
 // cap-counter). composeFeatures (auth-mode) ergänzt config + secrets +
 // auth-email-password automatisch.

package/samples/apps/config-demo/src/features/demo/feature.ts

@@ -37,8 +37,8 @@ const REQUIRED_I18N = {
 // mask.title ist der i18n-Key des Feld-Labels, mask.order die Reihenfolge.
 export const configDemoFeature = defineFeature("config-demo", (r) => {
   r.translations({ keys: REQUIRED_I18N });
-  r.requires("config");
-  r.requires("secrets");
+  r.requires({ features: ["config"] });
+  r.requires({ features: ["secrets"] });
 
   r.config({
     keys: {

package/samples/apps/styleguide/src/features/ai-settings/feature.ts

@@ -53,14 +53,14 @@ function isProvider(value: unknown): value is Provider {
 }
 
 export const aiSettingsFeature = defineFeature("ai-settings", (r) => {
-  r.requires("config");
+  r.requires({ features: ["config"] });
   r.translations({ keys: AI_SETTINGS_I18N });
 
   r.crud("connection", connectionEntity, { write: open, read: openRead });
-  r.queryHandler(
-    "connection-options",
-    noPayload,
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "connection-options",
+    schema: noPayload,
+    handler: async (query, ctx) => {
       const page = await executor.list({ limit: 100 }, query.user, ctx.db);
       return {
         rows: page.rows.map((row) => ({
@@ -69,28 +69,33 @@ export const aiSettingsFeature = defineFeature("ai-settings", (r) => {
         })),
       };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 
-  r.queryHandler(
-    "model-options",
-    connectionIdPayload,
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "model-options",
+    schema: connectionIdPayload,
+    handler: async (query, ctx) => {
       const { connectionId } = query.payload;
       if (connectionId === undefined) return { rows: [] };
       const row = await executor.detail({ id: connectionId }, query.user, ctx.db);
       const provider = row?.["provider"];
       return { rows: isProvider(provider) ? MODELS_BY_PROVIDER[provider] : [] };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 
-  r.queryHandler("step-options", noPayload, async () => ({ rows: AI_STEPS }), openRead);
+  r.queryHandler({
+    name: "step-options",
+    schema: noPayload,
+    handler: async () => ({ rows: AI_STEPS }),
+    ...openRead,
+  });
 
-  r.queryHandler(
-    "all-model-options",
-    noPayload,
-    async () => ({
+  r.queryHandler({
+    name: "all-model-options",
+    schema: noPayload,
+    handler: async () => ({
       rows: PROVIDERS.flatMap((provider) =>
         MODELS_BY_PROVIDER[provider].map((model) => ({
           ...model,
@@ -98,13 +103,13 @@ export const aiSettingsFeature = defineFeature("ai-settings", (r) => {
         })),
       ),
     }),
-    openRead,
-  );
+    ...openRead,
+  });
 
-  r.queryHandler(
-    "connection:summary",
-    idPayload,
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "connection:summary",
+    schema: idPayload,
+    handler: async (query, ctx) => {
       const row = await executor.detail({ id: query.payload.id }, query.user, ctx.db);
       return {
         id: query.payload.id,
@@ -112,12 +117,22 @@ export const aiSettingsFeature = defineFeature("ai-settings", (r) => {
         provider: String(row?.["provider"] ?? ""),
       };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 
   const acknowledged = async () => ({ isSuccess: true as const, data: null });
-  r.writeHandler("step:assign", z.object({}).passthrough(), acknowledged, open);
-  r.writeHandler("probe:run", z.object({}).passthrough(), acknowledged, open);
+  r.writeHandler({
+    name: "step:assign",
+    schema: z.object({}).passthrough(),
+    handler: acknowledged,
+    ...open,
+  });
+  r.writeHandler({
+    name: "probe:run",
+    schema: z.object({}).passthrough(),
+    handler: acknowledged,
+    ...open,
+  });
 
   r.config({
     keys: {

package/samples/apps/styleguide/src/features/demo/feature.ts

@@ -63,10 +63,10 @@ export const demoFeature = defineFeature("styleguide", (r) => {
   // triggers shouldRenderActionsIconOnly) and need their own write handlers.
   const { executor: itemExecutor } = createEntityExecutor("item", demoEntity);
 
-  r.writeHandler(
-    "item:archive",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) =>
+  r.writeHandler({
+    name: "item:archive",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (event, ctx) =>
       // Admin-style status flip from a list row: last-writer-wins is fine,
       // same as the tenant enable/disable toggle this mirrors.
       itemExecutor.update(
@@ -75,13 +75,13 @@ export const demoFeature = defineFeature("styleguide", (r) => {
         ctx.db,
         { skipOptimisticLock: true },
       ),
-    { access: open.access },
-  );
+    access: open.access,
+  });
 
-  r.writeHandler(
-    "item:publish",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) =>
+  r.writeHandler({
+    name: "item:publish",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (event, ctx) =>
       itemExecutor.update(
         {
           id: event.payload.id,
@@ -91,13 +91,13 @@ export const demoFeature = defineFeature("styleguide", (r) => {
         ctx.db,
         { skipOptimisticLock: true },
       ),
-    { access: open.access },
-  );
+    access: open.access,
+  });
 
-  r.writeHandler(
-    "item:duplicate",
-    z.object({ id: z.uuid() }),
-    async (event, ctx) => {
+  r.writeHandler({
+    name: "item:duplicate",
+    schema: z.object({ id: z.uuid() }),
+    handler: async (event, ctx) => {
       const source = await itemExecutor.detail({ id: event.payload.id }, event.user, ctx.db);
       if (!source) return failNotFound("item", event.payload.id);
       return itemExecutor.create(
@@ -115,8 +115,8 @@ export const demoFeature = defineFeature("styleguide", (r) => {
         ctx.db,
       );
     },
-    { access: open.access },
-  );
+    access: open.access,
+  });
 
   r.screen({
     id: "item-edit",