@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/build-config-feature-schema.js

@@ -1,19 +1,19 @@
-// Self-Populating Settings-Hub (config-provisioning Phase 2).
+// Self-Populating Settings Hub.
 //
-// Leitet aus den im Registry deklarierten Config-Keys automatisch die
-// Settings-UI ab: pro Audience (scope) einen Parent-Nav, pro (Feature ×
-// scope) einen configEdit-Screen + Child-Nav darunter. Kein manuelles
-// r.screen/r.nav am App-Author.
+// Derives the Settings UI automatically from the config keys declared in the
+// registry: one parent nav per audience (scope), and one configEdit screen plus
+// child nav per (feature × scope). App authors do not need manual
+// r.screen/r.nav declarations.
 //
-// Sichtbar wird nur ein Key MIT `mask` (siehe ConfigKeyDefinition): mask ist
-// die per-Key-Intent „user-facing Einstellung" und trägt zugleich das Label
-// (mask.title, ein i18n-Key). Keys ohne mask sind internes Plumbing
-// (ENV-provisioniert/computed) und erscheinen nicht.
+// Only a key WITH `mask` is visible (see ConfigKeyDefinition): mask is the
+// per-key intent for a “user-facing setting” and also supplies its label
+// (mask.title, an i18n key). Keys without mask are internal plumbing
+// (ENV-provisioned/computed) and are omitted.
 //
-// Die erzeugten Screens/Navs werden von buildAppSchema in die FeatureSchema
-// des config-Features (featureName "config") gemerged — der Renderer
-// qualifiziert die kurzen ids/refs mit "config". Daher hier durchweg KURZE
-// ids/parent/screen-Refs (buildNavRegistrySliceForApp qualifiziert selbst).
+// buildAppSchema merges the generated screens/navs into the FeatureSchema of
+// the config feature (featureName "config"). The renderer qualifies the short
+// ids/refs with "config", so this code consistently uses SHORT ids/parent/screen
+// refs (buildNavRegistrySliceForApp qualifies them itself).
 import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
 import { CONFIG_EDIT_ENTITY, fieldLabelKey } from "../i18n/required-surface-keys.js";
 import { isEncryptedAtRest } from "./config-helpers.js";
@@ -22,14 +22,15 @@ import { createBooleanField, createNumberField, createSelectField, createTextFie
 import { isKebabSegment, toKebab } from "./qualified-name.js";
 import { isFieldsEditSection, sectionFieldSpecs, } from "./screen-helpers.js";
 import { isOpenToAllGranted } from "./types/handlers.js";
-// Namespace, unter dem buildAppSchema die generierten Screens/Navs einhängt
-// (find-or-create FeatureSchema). MUSS gleich CONFIG_FEATURE aus dem config
-// bundled-feature sein — framework kann das const nicht importieren (Richtung
-// bundled-features → framework), darum hier gepinnt + Pin-Test bundled-seitig.
+// Namespace under which buildAppSchema attaches the generated screens/navs
+// (find-or-create FeatureSchema). It MUST match CONFIG_FEATURE from the config
+// bundled feature. The framework cannot import that constant because of the
+// bundled-features → framework dependency direction, so it is pinned here and
+// verified by a bundled-feature pin test.
 export const SETTINGS_HUB_FEATURE = "config";
-// Eigene Workspace nur für workspace-mode-Apps (siehe buildAppSchema): Settings
-// erscheinen als eigener Switcher-Eintrag, statt die kuratierten App-Workspaces
-// zu verschmutzen. Apps ohne Workspaces zeigen die Navs über den no-filter-Pfad.
+// A dedicated workspace for workspace-mode apps (see buildAppSchema): Settings
+// appear as their own switcher entry instead of cluttering the curated app
+// workspaces. Apps without workspaces expose these navs through the no-filter path.
 export const SETTINGS_HUB_WORKSPACE = "settings";
 // Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
 const SCOPE_ORDER = { system: 10, tenant: 20, user: 30 };
@@ -54,21 +55,21 @@ const SECRETS_SECTION_DESCRIPTION_KEY = "config.secrets.description";
 const audienceNavShortId = (scope) => `audience-${scope}`;
 // Generated post-boot, never via r.nav() — the boot validator exempts exactly these QNs (an app references one to place the settings group inline).
 export const SETTINGS_HUB_AUDIENCE_NAV_QNS = SCOPES_BROAD_TO_DEEP.map((scope) => `${SETTINGS_HUB_FEATURE}:nav:${audienceNavShortId(scope)}`);
-// An einem Scope BREITER als der Home-Scope eines Keys darf nur eine für DIESE
-// Ebene privilegierte Rolle den (Cascade-)Default setzen — SystemAdmin auf
-// system, TenantAdmin/Admin auf tenant. Am Home-Scope gilt das volle write-Set
-// (unverändertes Verhalten). So liefert ein tenant-Home-Key wie SMTP zusätzlich
-// einen SystemAdmin-only Plattform-Screen; ein Key, dessen write-Set keine
-// dieser Rollen nennt, bekommt keinen breiteren Screen (write-Set = opt-in).
+// At a scope broader than a key's home scope, only a role privileged for THAT
+// level may set the cascade default—SystemAdmin at system, TenantAdmin/Admin at
+// tenant. The home scope retains the full write set (unchanged behavior). Thus a
+// tenant-home key such as SMTP also gets a SystemAdmin-only platform screen; a
+// key whose write set names none of these roles gets no broader screen (the write
+// set is the opt-in).
 const ELEVATED_ROLES = {
     system: ["SystemAdmin"],
     tenant: ["TenantAdmin", "Admin"],
     user: [],
 };
-// Der interne Maschinen-Akteur (access.system). Ein Key, den NUR diese Rolle
-// schreiben darf, ist provisioned-not-user-facing: er gehört nicht in den
-// menschlichen Hub (sonst rendert ein Feld, das der sichtbare Mensch nicht
-// speichern kann). `as const` für Literal-Verengung am Vergleich.
+// The internal machine actor (access.system). A key writable ONLY by this role
+// is provisioned-not-user-facing and must not enter the human hub; otherwise the
+// UI would render a field that the visible user cannot save. `as const` narrows
+// the literal for the comparison.
 const MACHINE_WRITE_ROLE = "system";
 const NO_SELECTOR_GATING = {
     pluginsByOwnerGroup: new Map(),
@@ -442,7 +443,7 @@ function buildScopeResult(scope, masked, secretsEnabled, secretsWriteHandler, de
         : NO_SELECTOR_GATING;
     const screens = [];
     const navs = [];
-    // Audience-Parent: Gruppierungs-Knoten ohne Screen.
+    // Audience parent: grouping node without a screen.
     navs.push({
         id: audienceNavShortId(scope),
         label: `config.settings.${scope}`,
@@ -624,10 +625,10 @@ function effectiveWriteRoles(def, scope) {
     const elevated = ELEVATED_ROLES[scope];
     return def.access.write.filter((r) => elevated.includes(r));
 }
-// navMembers tragen die QUALIFIZIERTEN Nav-QNs (siehe build-app-schema.test:
-// admin.navMembers === ["orders:nav:list", ...]). Die generierten Navs leben
-// unter SETTINGS_HUB_FEATURE, also `config:nav:<shortId>`. Sortiert = stabile
-// Landing-Screen-Wahl (firstNavScreenId iteriert navMembers der Reihe nach).
+// navMembers contain QUALIFIED nav QNs (see build-app-schema.test:
+// admin.navMembers === ["orders:nav:list", ...]). The generated navs live under
+// SETTINGS_HUB_FEATURE, namely `config:nav:<shortId>`. Sorting provides stable
+// landing-screen selection (firstNavScreenId iterates navMembers in order).
 function buildSettingsWorkspace(navs) {
     const navMembers = navs.map((n) => `${SETTINGS_HUB_FEATURE}:nav:${n.id}`).sort();
     return {
@@ -636,11 +637,10 @@ function buildSettingsWorkspace(navs) {
             label: "config.settings.title",
             icon: "settings",
             order: 1000,
-            // Union der Zugriffs-Regeln der bereits generierten (machine-gefilterten)
-            // Hub-Navs — sonst sieht ein unprivilegierter User einen leeren
-            // "Settings"-Switcher. Aus den Navs statt aus `masked`, damit die
-            // machine-only "system"-Rolle (die in keinem Nav steht) nicht ins
-            // Switcher-Gate leakt.
+            // Union of the access rules for the already generated (machine-filtered) Hub
+            // navs; otherwise an unprivileged user would see an empty "Settings"
+            // switcher. Use the navs rather than `masked` so the machine-only
+            // "system" role, which appears in no nav, cannot leak into the switcher gate.
             access: unionAccessRules(navs.map((n) => n.access)),
         },
         navMembers,
@@ -830,14 +830,14 @@ function maskOrder(k) {
 function minMaskOrder(keys) {
     return Math.min(...keys.map(maskOrder));
 }
-// Der Hub ist zum Editieren — wer mindestens einen Key der Gruppe SCHREIBEN
-// darf, sieht den Settings-Eintrag (write, nicht read). Das hält system-scope
-// (write default `["system"]`) human-hidden bis der Autor write: SystemAdmin
-// opt-int, und zeigt user-scope (write `all`) jedem. `all` lässt sich in
-// AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
-// per Key gegated.
-// Union der Navs-Access-Regeln: ein openToAll-Nav öffnet das ganze Gate, sonst
-// die Vereinigung der Rollen. undefined-access-Navs tragen nichts bei.
+// The hub is for editing: anyone allowed to WRITE at least one key in the group
+// sees the Settings entry (write, not read). This keeps system-scope (write
+// default `["system"]`) hidden from humans until the author opts in with
+// write: SystemAdmin, while user-scope (write `all`) is shown to everyone.
+// `all` can only be represented as openToAll in AccessRule; writes remain
+// gated per key on the server.
+// Access rules for navs are unioned: an openToAll nav opens the whole gate;
+// otherwise roles are combined. Navs without access rules contribute nothing.
 function unionAccessRules(rules) {
     const roles = [];
     for (const rule of rules) {
@@ -852,8 +852,8 @@ function unionAccessRules(rules) {
     }
     return rolesToAccess(roles);
 }
-// `all` lässt sich in AccessRule nur als openToAll ausdrücken; der Write bleibt
-// server-seitig per Key gegated.
+// `all` can only be represented as openToAll in AccessRule; writes remain gated
+// per key on the server.
 function rolesToAccess(roles) {
     if (roles.includes("all"))
         return {

package/dist/engine/build-target.js

@@ -1,33 +1,30 @@
-// buildTarget — typed Builder für TargetRef.
+// buildTarget — typed builder for TargetRef.
 //
-// **Was er macht.** Erzeugt einen TargetRef, dessen action + args
-// compile-time gegen die treeActions-Map des Ziel-Features validiert
-// sind. Magic-String-URIs werden nirgends hand-getippt; das ist die
-// Single-Source-of-Truth für Cross-Feature-Linking im Visual-Tree.
+// **What it does.** Creates a TargetRef whose action and args are
+// validated at compile time against the target feature's treeActions map.
+// Magic-string URIs are never typed by hand; this is the single source
+// of truth for cross-feature linking in the visual tree.
 //
-// **Wie er typed.** Function-Overloads splitten Actions ohne args
-// (NoArgsAction) und Actions mit args (WithArgsAction). TS validiert:
-//   - action ist string-literal aus den Keys von treeActions
-//   - bei WithArgsAction sind args required und matchen
+// **How it is typed.** Function overloads separate actions without args
+// (NoArgsAction) from actions with args (WithArgsAction). TypeScript validates:
+//   - action is a string literal from the keys of treeActions
+//   - for WithArgsAction, args is required and matches
 //     treeActions[action]["args"]
-//   - bei NoArgsAction ist args nicht erlaubt
+//   - for NoArgsAction, args is not allowed
 //
-// **Phase 0.** Das Feature-Handle ist hier eine generische Constraint
-// (FeatureWithTreeActions). In Schicht 2 wird treeActions ein
-// Pattern-Type im Feature-AST und defineFeature exposed eine
-// treeActions-Slot mit gleichem Shape — dann passen real Features
-// drauf, ohne Builder-Änderung.
-//
-// Siehe docs/plans/architecture/visual-tree.md A5.
-// TypeGuard für args: Overloads garantieren ein Plain-Object, aber die
-// Implementation-Signature sieht args als unknown (TArgs ist erased zur
-// Laufzeit). Der Guard validiert die Plain-Object-Convention runtime
-// statt einen `as`-Cast zu setzen — siehe coding-standards.md.
+// **Feature handle.** It is currently a generic constraint
+// (FeatureWithTreeActions). Once treeActions becomes a pattern type in the
+// feature AST and defineFeature exposes a treeActions slot with the same
+// shape, real features will fit without changing the builder.
+// Type guard for args: overloads guarantee a plain object, but the
+// implementation signature sees args as unknown (TArgs is erased at
+// runtime). The guard validates the plain-object convention at runtime
+// instead of using an `as` cast.
 function isArgsObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-// Implementation — args ist `unknown` weil die Overloads-Generic-TArgs
-// zur Laufzeit erased ist. Plain-Object-Convention via TypeGuard.
+// Implementation — args is `unknown` because the overloads' generic TArgs
+// is erased at runtime. The plain-object convention is enforced via the type guard.
 export function buildTarget(spec) {
     if (!isArgsObject(spec.args)) {
         return Object.freeze({

package/dist/engine/codemod/pipeline-codemod.js

@@ -1,9 +1,8 @@
-// biome-ignore-all lint/suspicious/noConsole: CLI tool — console.log is the output
 // biome-ignore-all lint/style/noNonNullAssertion: regex capture-group indexing — match-success implies non-null capture
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { Glob } from "bun";
-import { Project, SyntaxKind } from "ts-morph";
+import { Node, Project, SyntaxKind } from "ts-morph";
 export function analyzeHandlerArrow(arrowText) {
     const text = arrowText.trim();
     let handlerBodyText;
@@ -53,24 +52,30 @@ export function analyzeHandlerArrow(arrowText) {
                 l.startsWith("for ") ||
                 l.startsWith("while ") ||
                 l.startsWith("} else"));
-            const createMatch = handlerBodyText.match(/const\s+(\w+)\s*=\s*await\s+(\w+)\.create\s*\(/);
+            const [, createVar, createExecutor] = handlerBodyText.match(/const\s+(\w+)\s*=\s*await\s+(\w+)\.create\s*\(/) ?? [];
             const updateMatch = handlerBodyText.match(/const\s+(\w+)\s*=\s*await\s+(\w+)\.update\s*\(/);
             const hasSimpleReturn = /return\s*\{[^}]*isSuccess:\s*true/.test(handlerBodyText);
-            if (createMatch && hasSimpleReturn && !hasConditionalLogic) {
+            if (createVar !== undefined &&
+                createExecutor !== undefined &&
+                hasSimpleReturn &&
+                !hasConditionalLogic) {
                 isSimpleExecutorCreate = true;
-                executorName = createMatch[2];
-                executorCreateVar = createMatch[1];
-                executorCreateArgs = extractArgs(handlerBodyText, createMatch[2], "create");
+                executorName = createExecutor;
+                executorCreateVar = createVar;
+                executorCreateArgs = extractArgs(handlerBodyText, createExecutor, "create");
             }
-            else if (createMatch && hasSimpleReturn && hasConditionalLogic) {
+            else if (createVar !== undefined &&
+                createExecutor !== undefined &&
+                hasSimpleReturn &&
+                hasConditionalLogic) {
                 // Try to match the guard pattern: if (!<var>.isSuccess) { return fail } return success
-                const guard = extractGuardedPattern(handlerBodyText, createMatch[1]);
+                const guard = extractGuardedPattern(handlerBodyText, createVar);
                 if (guard) {
                     isGuardedCreate = true;
                     guardConfig = guard;
-                    executorName = createMatch[2];
-                    executorCreateVar = createMatch[1];
-                    executorCreateArgs = extractArgs(handlerBodyText, createMatch[2], "create");
+                    executorName = createExecutor;
+                    executorCreateVar = createVar;
+                    executorCreateArgs = extractArgs(handlerBodyText, createExecutor, "create");
                 }
             }
             if (updateMatch &&
@@ -312,6 +317,8 @@ function inferSchemaType(objLiteral) {
     const schemaProp = objLiteral.getProperty("schema");
     if (!schemaProp)
         return "unknown";
+    if (!Node.isPropertyAssignment(schemaProp))
+        return "unknown";
     const init = schemaProp.getInitializer();
     if (!init)
         return "unknown";
@@ -431,7 +438,7 @@ function ensurePipelineImport(content) {
     const importRegex = /import\s*\{([^}]*)\}\s*from\s*["']@cosmicdrift\/kumiko-framework\/engine["']/;
     const match = content.match(importRegex);
     if (match) {
-        const existingImports = match[1].trim();
+        const existingImports = (match[1] ?? "").trim();
         const newImports = existingImports ? `${existingImports}, stepsPipeline` : "stepsPipeline";
         return content.replace(importRegex, `import { ${newImports} } from "@cosmicdrift/kumiko-framework/engine"`);
     }

package/dist/engine/config-helpers.js

@@ -10,9 +10,9 @@ export function isEncryptedAtRest(def) {
 // --- Access Presets ---
 export const access = {
     all: ["all"], // @cast-boundary schema-walk
-    // TenantAdmin zusätzlich: bundled-features vergeben "TenantAdmin",
-    // App-Repos historisch "Admin" — das Preset deckt beide ab, sonst
-    // driftet die writeRole-Spalte der Feature-Reference (Manifest 243/2).
+    // Bundled features use "TenantAdmin", while app repositories historically use
+    // "Admin"; including both prevents the feature reference's writeRole from
+    // drifting.
     admin: ["TenantAdmin", "Admin", "SystemAdmin"], // @cast-boundary schema-walk
     systemAdmin: ["SystemAdmin"], // @cast-boundary schema-walk
     system: ["system"], // @cast-boundary schema-walk
@@ -25,7 +25,7 @@ export const access = {
     // also set via ctx.systemWriteAs (roles = [SYSTEM_ROLE]). Stays human-writable
     // because checkWriteAccess only collapses to system-only when system is the
     // SOLE writer (humanWriters empty). Composes any preset, so apps with custom
-    // roles get the same provisioning path (issue #396).
+    // roles get the same provisioning path.
     withSystem: (roles) => [SYSTEM_ROLE, ...roles],
 };
 // --- Scope Defaults ---

package/dist/engine/constants.js

@@ -31,7 +31,7 @@ export const LifecycleHookTypes = {
 // --- Config Scopes ---
 // Value object satisfies the canonical ConfigScope union from kumiko-types —
 // a scope added here without a matching kumiko-types member is now a
-// compile error instead of silent drift (#1423/#1439).
+// compile error instead of silent drift.
 export const ConfigScopes = {
     system: "system",
     tenant: "tenant",
@@ -65,7 +65,7 @@ void _concurrencyModeExhaustive;
 // --- Money Currency Sources ---
 // Canonical definition lives in kumiko-types/fields (client-safe, next to
 // MoneyCurrencySource) so renderer code can import it without pulling in
-// runtime-only engine code (fw#2937). Re-exported here for server callers
+// runtime-only engine code. Re-exported here for server callers
 // already importing framework/engine (bundled-features/src/tenant-settings/
 // constants.ts TenantSettingsConfig.currency reuses this same constant, so
 // the two stay in sync by construction).

package/dist/engine/create-app.js

@@ -11,7 +11,7 @@ function inlineFormFieldMaps(screen) {
         return [];
     return screen.confirm !== undefined ? [screen.fields, screen.confirm.fields] : [screen.fields];
 }
-// `currency: { kind: "literal", code }` (fw#2839) is only meaningful for a
+// `currency: { kind: "literal", code }` is only meaningful for a
 // code the app knows — a typo would otherwise render and submit amounts in a
 // currency no formatter or rate table covers.
 function validateLiteralCurrencyCode(where, field, currencies) {
@@ -106,7 +106,7 @@ export function createApp(config) {
             }
         }
         // A money field on an entity-less form screen names its own currency
-        // source (fw#2839) — a literal code has to be one the app actually knows,
+        // source — a literal code has to be one the app actually knows,
         // same rule the entity `defaultCurrency` check above applies.
         for (const [screenId, screen] of Object.entries(feature.screens ?? {})) {
             const inlineFields = inlineFormFieldMaps(screen);

package/dist/engine/define-feature.js

@@ -48,17 +48,25 @@ export function defineFeature(name, setup, settings) {
         },
         requires: (() => {
             const fn = (...args) => {
-                if (!args.every(isObjectArgument))
+                const [first, ...rest] = args;
+                if (rest.length > 0 || !isObjectArgument(first)) {
                     throwObjectArgumentRequired(name, "requires");
-                state.requires.push(...resolveFeatureNamesArgs(args));
+                }
+                // Untyped callers can pass `{ feature: [...] }`; without this the object would be
+                // registered as a dependency name.
+                if (!Array.isArray(first.features) || !first.features.every((f) => typeof f === "string")) {
+                    throw new Error(`[Feature ${name}] r.requires() needs { features: string[] }`);
+                }
+                state.requires.push(...first.features);
             };
-            fn.projection = (tableName) => {
-                state.requiredProjections.add(tableName);
-            };
-            fn.step = (stepKind) => {
-                state.requiredSteps.add(stepKind);
-            };
-            return fn;
+            return Object.assign(fn, {
+                projection: (tableName) => {
+                    state.requiredProjections.add(tableName);
+                },
+                step: (stepKind) => {
+                    state.requiredSteps.add(stepKind);
+                },
+            });
         })(),
         optionalRequires(...args) {
             state.optionalRequires.push(...resolveFeatureNamesArgs(args));
@@ -106,10 +114,10 @@ export function defineFeature(name, setup, settings) {
             postDelete: state.phasedLifecycleHooks.postDelete,
             preQuery: state.lifecycleHooks["preQuery"] ?? {},
             postQuery: state.lifecycleHooks["postQuery"] ?? {},
-            // @cast-boundary engine-bridge — die Hook-Registrierung erased die
-            // per-Slot-Signaturen zu LifecycleHookFn (Union, s. Cast in
-            // addLifecycleHook); die Branches dort sind die einzigen Producer und
-            // schreiben pro Slot typrichtig.
+            // @cast-boundary engine-bridge — hook registration erases the per-slot
+            // signatures to LifecycleHookFn (a union; see the cast in
+            // addLifecycleHook). The branches there are the only producers and write
+            // the correct type for each slot.
         },
         entityHooks: {
             postSave: state.entityPostSave,

package/dist/engine/define-handler.js

@@ -7,6 +7,10 @@ function pickPreTransactionPhases(def) {
         ...(def.beforeTransaction && { beforeTransaction: def.beforeTransaction }),
     };
 }
+// `in` keeps both branches of the discriminated union readable regardless of narrowing.
+function hasHandlerAndPerform(def) {
+    return ("handler" in def && def.handler !== undefined && "perform" in def && def.perform !== undefined);
+}
 export function defineWriteHandler(def, 
 // R6: a phantom rest-param. When the inferred response `TData` carries a
 // Secret<> anywhere, ContainsSecret<TData> is `true` and this resolves to a
@@ -32,13 +36,10 @@ export function defineWriteHandler(def,
     // The discriminated-union type-error
     //   "Type 'PipelineDef<...>' is not assignable to type 'undefined'."
     // is functional but cryptic for less TS-experienced users; this throws
-    // a name-and-explanation error message instead. Followup #3.
-    // The cast is necessary because the discriminated union narrows
-    // `handler` away once `perform` is present (and vice-versa) — at this
-    // boundary we want to read both regardless of the narrowing.
-    const probe = def;
-    if (probe.handler !== undefined && probe.perform !== undefined) {
-        throw new Error(`defineWriteHandler("${def.name}"): both \`handler\` and \`perform\` are set. ` +
+    // a name-and-explanation error message instead.
+    const handlerName = def.name;
+    if (hasHandlerAndPerform(def)) {
+        throw new Error(`defineWriteHandler("${handlerName}"): both \`handler\` and \`perform\` are set. ` +
             `Pick one — \`handler\` for the free-form async function, ` +
             `\`perform: stepsPipeline(...)\` for the step-pipeline form. ` +
             `(See step-vocabulary.md for which form fits.)`);
@@ -56,6 +57,7 @@ export function defineWriteHandler(def,
         ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
+        ...(def.rateLimitCost && { rateLimitCost: def.rateLimitCost }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
         ...pickPreTransactionPhases(def),
         ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
@@ -103,10 +105,10 @@ export function isEntityConventionQueryHandler(def) {
 }
 // A projectionList screen's query must resolve to { rows, nextCursor, total? }
 // (CursorResult<T>) — the renderer used to read rowsQuery.data?.rows and
-// silently show an empty list otherwise (fw#2216: session-list); the
-// renderer now guards against a malformed shape at runtime instead. Use this
-// instead of defineQueryHandler for any query wired to a projectionList
-// screen's `query` so the contract is documented at the definition site.
+// silently show an empty list otherwise; the renderer now guards against a
+// malformed shape at runtime instead. Use this instead of defineQueryHandler
+// for any query wired to a projectionList screen's `query` so the contract is
+// documented at the definition site.
 //
 // Deliberately does NOT merge cursor/limit/sort/search into the input
 // schema — that would change sortable/paginated derivation for existing

package/dist/engine/define-step.js

@@ -4,7 +4,7 @@
 // (run-pipeline.ts) looks them up by `kind` to dispatch run-calls.
 //
 // The registry is process-global; Tier-2 step opt-in via
-// `r.requires.step("…")` (Q9 in step-vocabulary.md) is a future pass.
+// `r.requires.step("…")` is a future pass.
 const stepRegistry = new Map();
 export function defineStep(def) {
     const existing = stepRegistry.get(def.kind);

package/dist/engine/define-workflow.d.ts

@@ -22,9 +22,9 @@ export type WorkflowDefinition<TPayload = unknown, TData = unknown, TAwaits exte
     readonly name: string;
     readonly trigger: WorkflowTrigger;
     /**
-     * Declared expected events (D4, workflow-resume-loop.md) — the sole route
+     * Declared expected events (workflow-resume-loop.md) — the sole route
      * a waitForEvent step can reach an event type. Read at registration time
-     * to build the static apply-map (Phase 3b); values are plain event-type
+     * to build the static apply-map; values are plain event-type
      * strings, not the branded AwaitedEventType the pipeline closure sees.
      */
     readonly awaits?: TAwaits;
@@ -70,17 +70,17 @@ export type WorkflowInput<TPayload = unknown, TData = unknown, TAwaits extends R
  */
 export declare function defineWorkflow<TPayload = unknown, TData = unknown, const TAwaits extends Record<string, string> = Record<string, string>>(input: WorkflowInput<TPayload, TData, TAwaits>): WorkflowDefinition<TPayload, TData, TAwaits>;
 /**
- * Q7 Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
+ * Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
  * identity (name + trigger + serialized pipeline-closure source). Persisted
  * in `workflow.run.started` and re-checked at every resume so a library-
  * upgrade that changes the closure source surfaces as a loud
  * `workflow-definition-changed` failure on in-flight runs instead of a
  * silent semantic drift.
  *
- * Limitations (will be tightened in M.5 with the Designer/AST layer):
+ * Limitations (will be tightened with the Designer/AST layer):
  *   - `build.toString()` captures the closure source but not bindings —
  *     two definitions that import different external helpers with the
- *     same source bytes would collide. Acceptable for M.4 because the
+ *     same source bytes would collide. Acceptable because the
  *     fingerprint is a *change-detector*, not a deep semantic identity.
  *   - Minifiers / source-maps will produce different fingerprints across
  *     environments. Run-the-fingerprint-in-the-same-environment is the

package/dist/engine/define-workflow.js

@@ -1,7 +1,7 @@
 // defineWorkflow — define a persistent, suspendable workflow.
 // Tier-3 / Workflow-only mount-point. See step-vocabulary.md Sample 2 for
 // the full lifecycle (run.started → wait → resume → run.completed) and
-// Q7 (Snapshot-at-Start) for the in-flight upgrade story.
+// Snapshot-at-Start for the in-flight upgrade story.
 import { createHash } from "node:crypto";
 /**
  * Define a suspendable workflow.
@@ -39,27 +39,27 @@ export function defineWorkflow(input) {
     };
 }
 /**
- * Q7 Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
+ * Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
  * identity (name + trigger + serialized pipeline-closure source). Persisted
  * in `workflow.run.started` and re-checked at every resume so a library-
  * upgrade that changes the closure source surfaces as a loud
  * `workflow-definition-changed` failure on in-flight runs instead of a
  * silent semantic drift.
  *
- * Limitations (will be tightened in M.5 with the Designer/AST layer):
+ * Limitations (will be tightened with the Designer/AST layer):
  *   - `build.toString()` captures the closure source but not bindings —
  *     two definitions that import different external helpers with the
- *     same source bytes would collide. Acceptable for M.4 because the
+ *     same source bytes would collide. Acceptable because the
  *     fingerprint is a *change-detector*, not a deep semantic identity.
  *   - Minifiers / source-maps will produce different fingerprints across
  *     environments. Run-the-fingerprint-in-the-same-environment is the
  *     contract; cross-env replay is out of scope.
  */
 export function computeDefinitionFingerprint(workflow) {
-    // `awaits` is part of the routing contract (D4, workflow-resume-loop.md):
+    // `awaits` is part of the routing contract (workflow-resume-loop.md):
     // changing which events a run waits on changes the run's behavior just
     // like changing the step source does, so a changed declaration must flip
-    // the fingerprint and trip the Q7 stale-definition check on resume.
+    // the fingerprint and trip the stale-definition check on resume.
     const material = JSON.stringify({
         name: workflow.name,
         trigger: workflow.trigger,

package/dist/engine/entity-handlers.d.ts

@@ -44,6 +44,19 @@ export declare const entityListSchema: z.ZodObject<{
         }>;
         value: z.ZodUnknown;
     }, z.core.$strip>>>;
+    aggregate: z.ZodOptional<z.ZodObject<{
+        groupBy: z.ZodOptional<z.ZodString>;
+        measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            kind: z.ZodEnum<{
+                avg: "avg";
+                count: "count";
+                max: "max";
+                min: "min";
+                sum: "sum";
+            }>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
 export declare function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;