@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/engine/pattern-library/index.js

@@ -1,3 +1,3 @@
-// Public API of the pattern-library — Designer (C5/C6), AI-Builder (L2),
-// MCP-Server (L9) consume from here.
+// Public API of the pattern-library — Designer, AI-Builder,
+// MCP-Server consume from here.
 export { getPatternSchema, groupByCategory, PATTERN_LIBRARY } from "./library.js";

package/dist/engine/pattern-library/library.js

@@ -1,6 +1,6 @@
 // Pattern-Library — concrete FormSchema entries for every FeaturePattern
-// kind. Centralised here so the Designer (C5/C6), the AI-Builder (L2),
-// and the MCP-Server (L9) share one source-of-truth for "how does this
+// kind. Centralised here so the Designer, the AI-Builder,
+// and the MCP-Server share one source-of-truth for "how does this
 // pattern look as a form?".
 //
 // **Updating contract:** when a new pattern-kind gets a parser/renderer

package/dist/engine/pattern-library/types.js

@@ -1,7 +1,7 @@
 // Forms-Schema metadata — describes how a FeaturePattern is rendered as
 // a Designer form, fed to an LLM as a JSON-Schema, or surfaced in the
 // MCP-Server tool list. One schema, three consumers — that's the whole
-// point of factoring this out of the hand-rolled C5 skeleton.
+// point of factoring this out of the hand-rolled skeleton.
 //
 // **NOT a DSL.** The Source-of-Truth for a feature stays
 // `defineFeature.ts` — the AST-visitor (feature-ast/parse.ts) reads it
@@ -10,7 +10,7 @@
 // already-parsed FeaturePattern in a form. No alternative parser, no
 // alternative syntax, no second canonical representation.
 //
-// **Vokabular** (12 input-types):
+// **Vocabulary** (12 input-types):
 //
 //   text                  — single-line string (name / label / id)
 //   textarea              — multi-line string (description / SQL / readme)
@@ -31,6 +31,6 @@
 // FeaturePattern object using dot-separated keys (`definition.fields`,
 // `access.roles`, `templates.email`). Numeric indices use the bracket
 // form (`columns.0`). The Designer/LLM uses paths for read & write —
-// the patcher (C2) consumes pattern-level updates only, so paths are
+// the patcher consumes pattern-level updates only, so paths are
 // purely a UI concern at this stage.
 export {};

package/dist/engine/pipeline.js

@@ -8,7 +8,7 @@
 // the resolver-side PipelineCtx (run-pipeline.ts). Resolvers that need
 // prior step results destructure them from the resolver's ctx.
 //
-// Renamed from `pipeline()` (Followup #1) — it shared its name with the
+// Renamed from `pipeline()` — it shared its name with the
 // internal `packages/framework/src/pipeline/` directory (dispatcher,
 // lifecycle, outbox-poller), which made repo-wide grep for `pipeline`
 // return mixed results.
@@ -76,7 +76,7 @@ export function stepsPipeline(closure) {
 // awaits map wired into the closure. The cast below is the one place a
 // workflow's raw declared event-type strings become AwaitedEventType — safe
 // because pipelineDef.awaits only ever holds what defineWorkflow's `awaits`
-// carried in (D4, workflow-resume-loop.md), never an unchecked external
+// carried in (workflow-resume-loop.md), never an unchecked external
 // value.
 export function buildPipelineSteps(pipelineDef, event) {
     const steps = pipelineDef.build({

package/dist/engine/project-app-schema-for-roles.js

@@ -1,4 +1,4 @@
-// Per-role projection of a fully-built AppSchema (fw#3314). GET /api/schema
+// Per-role projection of a fully-built AppSchema. GET /api/schema
 // used to ship the same full schema — screens, navs, workspaces, content
 // collections — to every authenticated user regardless of role, relying on
 // client-side UI checks (isUiAccessGranted) alone to hide what a role

package/dist/engine/projection-helpers.js

@@ -1,27 +1,27 @@
 import { updateMany } from "../db/query.js";
-// Typed-Apply-Helper für r.projection.apply: erlaubt per-event-type
-// typed event.payload-Access ohne SingleStreamApplyFn-Generic durch die
-// ganze ProjectionDefinition propagieren zu müssen.
+// Typed apply helper for r.projection.apply: enables typed event.payload
+// access per event type without propagating a SingleStreamApplyFn generic
+// through the entire ProjectionDefinition.
 //
-// Der Helper ist ein purer Type-Vehikel — zur Laufzeit identitäts-fn:
+// The helper is purely a type vehicle — an identity function at runtime:
 //
 //   apply: {
 //     "user.created": defineApply<UserCreatedPayload>(async (event, tx, table) => {
-//       // event.payload ist UserCreatedPayload, nicht Record<string, unknown>.
+//       // event.payload is UserCreatedPayload, not Record<string, unknown>.
 //       // Write through the passed `table` (ES-blessed inside apply), not a
 //       // closed-over branded constant.
 //       await insertOne(tx, table, { id: event.aggregateId, ...event.payload });
 //     }),
 //   }
 //
-// Default-Generic = Record<string, unknown> behält rückwärtskompatibles
-// Verhalten für Apply-Handler die ohne Type-Argument geschrieben sind. Der
-// `table`-Param ist optional zu nutzen — 2-arg-Applies bleiben gültig.
+// The default generic, Record<string, unknown>, preserves backward-compatible
+// behavior for apply handlers written without a type argument. The `table`
+// parameter is optional to use, so 2-argument applies remain valid.
 export function defineApply(fn) {
     // @cast-boundary engine-bridge — typed user-fn → erased internal storage
     return fn;
 }
-// Pendant für r.multiStreamProjection.apply — bekommt zusätzlich ctx.
+// Counterpart for r.multiStreamProjection.apply — also receives ctx.
 export function defineMspApply(fn) {
     // @cast-boundary engine-bridge — typed user-fn → erased internal storage
     return fn;

package/dist/engine/qualified-name.js

@@ -32,7 +32,7 @@ function validateSegment(value, label, context) {
 }
 // registry-ingest.ts also qualifies handlers/projections with these two —
 // not in the public QnTypes enum, but reachable as a type segment the same
-// way (#1991).
+// way.
 const NON_ENUM_QN_TYPES = ["stream", "projection", "workspace"];
 // Every segment word that a fully-qualified QN can carry as its type.
 const RESERVED_QN_SEGMENTS = new Set([
@@ -44,7 +44,7 @@ const RESERVED_QN_SEGMENTS = new Set([
 // the trailing part. Both signals must hold together: the scope alone
 // repeating (e.g. entity "user:create" on feature "user") or a reserved word
 // alone appearing (e.g. "compliance:query:for-tenant") are both common,
-// legitimate sub-structure on their own (#1991).
+// legitimate sub-structure on their own.
 function isDoubleQualified(scope, segments) {
     const [first, second] = segments;
     return first === scope && second !== undefined && RESERVED_QN_SEGMENTS.has(second);

package/dist/engine/registry-facade.js

@@ -85,7 +85,7 @@ export function buildRegistryFacade(state) {
         getEntityPostQueryHooks(entityName, effectiveFeatures) {
             return filterOwned(state.entityPostQueryHooks.get(entityName), effectiveFeatures);
         },
-        // F3 — Search-Payload-Extension contributors for an entity. Used by
+        // Search-Payload-Extension contributors for an entity. Used by
         // `buildSearchDocument` in system-hooks.ts to enrich the indexed payload.
         // `effectiveFeatures` filters out contributors owned by feature-toggle-
         // disabled features (parallel to getEntityPostQueryHooks etc.).

package/dist/engine/registry-ingest.js

@@ -23,9 +23,9 @@ export function populateFeatureCore(state, feature) {
                 `collides with r.storeTable("${physical}") (feature "${clash.featureName}"). ` +
                 `Pick a different tableName — both would emit CREATE TABLE "${physical}".`);
         }
-        // Entity-vs-entity ist genauso fatal: zwei Entities mit explizitem,
-        // identischem tableName überschrieben sich hier vorher still —
-        // doppeltes CREATE TABLE bzw. eine Projektion frisst die andere.
+        // Entity-vs-entity collisions are equally fatal: two entities with an explicit,
+        // identical tableName previously overwrote each other silently here—
+        // causing duplicate CREATE TABLE statements or one projection to replace the other.
         if (clash?.kind === "entity") {
             throw new Error(`Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
                 `collides with entity "${clash.owner}" (feature "${clash.featureName}"). ` +
@@ -232,7 +232,7 @@ export function populateTranslations(state, feature) {
     // Translations prefixed with featureName: (i18next namespace convention).
     // Keys that already carry the feature's own namespace prefix (e.g. a nav
     // label referencing "cap-counter:nav.cap-list" verbatim) must NOT be
-    // re-prefixed, else server-side t() can never resolve them (#1105). Both
+    // re-prefixed, else server-side t() can never resolve them. Both
     // bare and qualified spellings for the same key are accepted; if a
     // feature defines both, whichever is declared last wins (Object.entries
     // = insertion order, not "qualified always wins").
@@ -263,7 +263,7 @@ export function populateHooks(state, feature) {
     mergeHookList(state.entityPreDeleteHooks, feature.entityHooks?.preDelete);
     mergeHookList(state.entityPostDeleteHooks, feature.entityHooks?.postDelete);
     mergeHookList(state.entityPostQueryHooks, feature.entityHooks?.postQuery);
-    // F3 search-payload-extensions: per-entity contributors merged additively
+    // Search-payload-extensions: per-entity contributors merged additively
     for (const [entityName, contributors] of Object.entries(feature.searchPayloadExtensions ?? {})) {
         const existing = state.searchPayloadExtensions.get(entityName) ?? [];
         for (const c of contributors)
@@ -460,10 +460,10 @@ export function populateScreensNavWorkspaces(state, feature) {
         const stored = { ...screenDef, id: qualified };
         state.screenMap.set(qualified, stored);
         state.screenFeatureMap.set(qualified, feature.name);
-        // entity-Index nur für Screens die direkt an einer Entity hängen.
-        // entityList/entityEdit haben `entity`; custom + actionForm haben
-        // keinen entity-Bezug (custom ist opaque, actionForm hat inline
-        // fields ohne Entity-Reference).
+        // Index only screens that are directly attached to an entity.
+        // entityList/entityEdit have `entity`; custom + actionForm do not reference
+        // an entity (custom is opaque, and actionForm has inline fields without
+        // an entity reference).
         if (stored.type === "entityList" || stored.type === "entityEdit") {
             const existing = state.screensByEntity.get(stored.entity) ?? [];
             existing.push(stored);
@@ -515,9 +515,9 @@ export function populateScreensNavWorkspaces(state, feature) {
             }
         }
     }
-    // Tree-Actions slot — at-most-one per feature (only-once-guard im
-    // registrar). Erased Map für Runtime-Lookup; compile-time-typed
-    // Surface läuft über FeatureDefinition.exports (TreeActionsHandle).
+    // Tree-Actions slot—at most one per feature (the only-once guard runs in
+    // the registrar). The Map is erased for runtime lookup; the compile-time-typed
+    // surface is exposed through FeatureDefinition.exports (TreeActionsHandle).
     if (feature.treeActions !== undefined) {
         state.treeActionsMap.set(feature.name, feature.treeActions);
     }

package/dist/engine/registry-state.js

@@ -5,25 +5,25 @@ import { asEntityTableMeta } from "../db/query.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { qualifyEntityName } from "./qualified-name.js";
 const IMPLICIT_PROJECTION_SUFFIX = "-entity";
-// Pro r.entity-Registration eine ImplicitProjection mit auto-generierten
-// apply-Handlern für die 4 Auto-Verben. Live-Pfad geht durch
-// EventStoreExecutor und schreibt direkt in die Tabelle; rebuildProjection
-// nutzt diese Definition um aus Events zu replayen. Beide rufen dieselbe
-// applyEntityEvent-Funktion → Live==Rebuild by-construction (verstärkt
-// durch implicit-projection-equivalence.integration.ts).
+// Each `r.entity` registration gets an implicit projection with generated
+// apply handlers for the four automatic verbs. The live path writes directly
+// to the table through EventStoreExecutor, while rebuildProjection replays
+// events through this definition. Both call applyEntityEvent, ensuring live
+// and rebuild use the same logic (also covered by
+// implicit-projection-equivalence.integration.ts).
 export function buildImplicitProjection(featureName, entityName, entity, qualify, backingTable, extensions = []) {
     const name = qualify(featureName, "projection", `${entityName}${IMPLICIT_PROJECTION_SUFFIX}`);
     // Backing table (r.entity({ name, ...def, backingTable })) is the one physical table
     // object shared by executor-writes, rebuild-replay, test-push and
-    // collectTableMetas — restoring the #255 invariant (test-push == generate).
+    // collectTableMetas — restoring the invariant (test-push == generate).
     // Validated as a superset of the field-derived columns so a field/table
     // disagreement fails at boot, not as a silent thin-vs-rich row.
     const drizzleTable = backingTable !== undefined
         ? resolveBackingTable(entityName, entity, backingTable)
         : buildEntityTable(entityName, entity);
     markExecutorManagedTable(drizzleTable);
-    // applyEntityEvent gibt ApplyResult zurück; SingleStreamApplyFn erwartet
-    // Promise<void>. Im rebuild-Pfad ist die Row irrelevant — wir discarden.
+    // applyEntityEvent returns ApplyResult, but SingleStreamApplyFn expects
+    // Promise<void>. The row is irrelevant during rebuild, so we discard it.
     const handler = async (event, tx) => {
         await applyEntityEvent(event, drizzleTable, entity, tx);
     };
@@ -35,10 +35,9 @@ export function buildImplicitProjection(featureName, entityName, entity, qualify
         // Registered for every entity so the erasure replays on rebuild.
         [`${entityName}.forgotten`]: handler,
     };
-    // Restore-Verb existiert nur für softDelete-Entities. Hard-Delete-
-    // Entities sollten keine restored-Events produzieren — würden sie es
-    // doch, würde applyEntityEvent intern als no-op laufen, aber wir
-    // registrieren den Handler gar nicht erst.
+    // The restore verb exists only for softDelete entities. Hard-delete entities
+    // should not produce restored events; if they did, applyEntityEvent would
+    // treat them as a no-op, so the handler is not registered.
     if (entity.softDelete) {
         apply[`${entityName}.restored`] = handler;
     }
@@ -230,8 +229,8 @@ function ownerEnabled(owner, effectiveFeatures) {
 // every hook entry (set by defineFeature), so there's no parallel
 // bookkeeping — just append.
 export function mergeHookList(map, source) {
-    // skip: optionaler entityHook-slot — features ohne postSave/preDelete/
-    // postDelete/postQuery lassen das slot undefined.
+    // skip: the optional entity-hook slot may be undefined when a feature has no
+    // postSave, preDelete, postDelete, or postQuery hooks.
     if (!source)
         return;
     for (const [name, fns] of Object.entries(source)) {
@@ -244,10 +243,9 @@ export function mergeHookList(map, source) {
 // Hook keys are handler QNs — hooks don't get their own QN, they're keyed by the handler they target.
 // The hookQnType indicates whether the targeted handler is a write or query handler.
 export function mergeHookListQualified(map, source, featureName, hookQnType) {
-    // skip: optionaler hook-slot — defineFeature materialisiert zwar alle
-    // Slots, aber hand-gebaute Definitionen an System-Grenzen (Fixtures,
-    // Partial-Boots, s. registry.test.ts) lassen sie weg. Leeres Record
-    // statt Object.entries(undefined)-Crash.
+    // skip: the optional hook slot may be omitted by hand-built definitions at
+    // system boundaries (fixtures and partial boots), even though defineFeature
+    // materializes every slot. This avoids Object.entries(undefined) crashing.
     if (!source)
         return;
     for (const [name, fns] of Object.entries(source)) {

package/dist/engine/registry-validate.js

@@ -144,7 +144,7 @@ export function applyExtensionUsages(state) {
         }
     }
 }
-// fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
+// labelField defaults to "id" (a UUID column) elsewhere, but a
 // searchable reference ILIKEs the label column — an implicit or explicit
 // "id" default would 500 on every search request. Fail at boot.
 function buildSearchableReferenceField(entityName, fieldName, field, entityMap) {
@@ -176,7 +176,7 @@ function buildSearchableReferenceField(entityName, fieldName, field, entityMap)
         labelField: field.labelField,
     };
 }
-// fw#2741: ORDER BY runs against the referenced row's label column, so the
+// ORDER BY runs against the referenced row's label column, so the
 // same explicit-labelField requirement as searchable applies — ordering by the
 // "id" default would be a UUID order that looks deliberate to the user.
 function buildSortableReferenceField(entityName, fieldName, field) {
@@ -230,12 +230,12 @@ export function buildSearchableSortableCaches(state) {
 }
 // Implicit-Projection pro r.entity — see buildImplicitProjection doc above.
 export function buildImplicitProjections(state, features) {
-    // Implicit-Projection pro r.entity. Macht die Entity-Tabelle rebaubar
-    // ohne dass Apps eine explizite r.projection schreiben müssen.
-    // Naming-Convention: `<feature>:projection:<entityName>-entity` — der
-    // "-entity"-Suffix unterscheidet implicit von explicit-Projections und
-    // vermeidet Kollisionen wenn jemand z.B. eine Cross-Aggregate-Projection
-    // mit Entity-Name registriert.
+    // Implicit projection for r.entity. Makes the entity table rebuildable
+    // without requiring apps to declare an explicit r.projection.
+    // Naming convention: `<feature>:projection:<entityName>-entity` — the
+    // "-entity" suffix distinguishes implicit from explicit projections and
+    // prevents collisions when someone registers, for example, a
+    // cross-aggregate projection using the entity name.
     for (const feature of features) {
         // extendEntityProjection targets must exist as r.entity in the SAME
         // feature — a typo'd entity name would otherwise vanish silently and the
@@ -651,7 +651,7 @@ export function validateLifecycleHookTargets(state) {
 }
 export function validateEntityHookTargets(state, features) {
     // Same logic for entity-keyed hooks — targets must reference existing entities.
-    // Memory `feedback_dead_hook_needs_second_consumer`: a typo silently registers
+    // A hook whose target has a typo silently registers
     // and never fires. Validates all four entity-hook types (postSave/preDelete/
     // postDelete/postQuery) — net cleanup of an existing antipattern, not a
     // postQuery-special.
@@ -810,7 +810,7 @@ export function computeHasRateLimitedHandler(state) {
     // Lua-script registration on Redis) when nobody opted in. Deliberately
     // stays limited to explicit, non-disabled `rateLimit` declarations —
     // `{ disabled: true }` must not auto-wire a resolver for an app that only
-    // opted OUT, and fw#2861's systemScope default only fires once a resolver
+    // opted OUT, and the systemScope default only fires once a resolver
     // already exists, so it must not force wantsL3 either.
     state.hasRateLimitedHandlerCached = (() => {
         for (const h of state.writeHandlerMap.values()) {
@@ -827,12 +827,12 @@ export function computeHasRateLimitedHandler(state) {
     })();
 }
 export function publishEventPiiCatalog(state) {
-    // Publish the event-PII catalog (#799): append() — the single write funnel
+    // Publish the event-PII catalog: append() — the single write funnel
     // into kumiko_events — encrypts catalogued payload fields regardless of
     // which path produced the event (ctx.appendEvent, MSP-apply, low-level
     // append in delivery/jobs loggers).
     //
-    // Defense-in-depth (fw#2558): defineEvent is the only producer of
+    // Defense-in-depth: defineEvent is the only producer of
     // EventDef.piiFields and already fails closed without a stance, but this
     // boot gate re-checks every registered event — a future producer that
     // forgets to run through defineEvent would otherwise leave a hole where

package/dist/engine/run-in.js

@@ -1,6 +1,6 @@
 // runIn lane-routing helpers. Tiny module on purpose: both buildServer
-// (MSP-consumer filter) and the boot-validator (Welle 2.6.c coverage
-// check) need the same resolution rule, and duplicating it in two places
+// (MSP-consumer filter) and the boot-validator (coverage check)
+// need the same resolution rule, and duplicating it in two places
 // invites drift — when the default changes, one site gets updated and
 // the other silently doesn't.
 //

package/dist/engine/run-pipeline.js

@@ -21,6 +21,8 @@
 // errors propagate to the dispatcher's catch which maps them to
 // WriteFailure / HTTP. "return" / "skip" / fallback strategies land in
 // later slices together with their own integration tests.
+import { InternalError } from "../errors/index.js";
+import { describeShape, isWriteResultShape } from "../pipeline/dispatcher-utils.js";
 import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
 import { SUSPEND_SENTINEL } from "./steps/_step-dispatch-constants.js";
@@ -112,6 +114,11 @@ export async function runStepList(steps, event, handlerCtx, stepsAcc, scopeAcc,
         }
         const key = stepDef.resultKey?.(instance.args);
         if (key === RETURN_RESULT_KEY) {
+            if (!isWriteResultShape(value)) {
+                throw new InternalError({
+                    message: `Step "${instance.kind}" at index ${i} must return a WriteResult, got ${describeShape(value)}`,
+                });
+            }
             return { kind: "return", result: value };
         }
         if (key !== undefined) {

package/dist/engine/schema-builder.js

@@ -16,10 +16,11 @@ export function isRepresentableAtScale(n, scale) {
     const tolerance = Math.abs(scaled) * 8 * Number.EPSILON + Number.EPSILON;
     return Math.abs(scaled - Math.round(scaled)) <= tolerance;
 }
-// Lexikografischer ISO-Vergleich — exakt für `yyyy-mm-dd` (date) und korrekt
-// für ISO-Datetime in konsistenter Repräsentation (gleiche Offset-/Präzisions-
-// Form). Bewusst ohne Date-API (no-date-api-Guard); die Tag-genaue Grenze
-// reicht für min/max-Use-Cases (z.B. Geburtsdatum nicht in der Zukunft).
+// Lexicographic ISO comparison — exact for `yyyy-mm-dd` (date) and correct
+// for ISO datetimes in a consistent representation (same offset/precision
+// form). Deliberately avoids the Date API (no-date-api-Guard); day-level
+// comparison is sufficient for min/max use cases (e.g. a birth date not in
+// the future).
 function withDateBounds(schema, min, max) {
     if (min === undefined && max === undefined)
         return schema;
@@ -127,8 +128,9 @@ export function fieldToZod(field, currencies, opts = {}) {
             return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
         }
         case "longText": {
-            // longText hat keine `format`-Variante (per type-design). Nur
-            // optional maxLength + required, sonst ein offener z.string().
+            // longText has no `format` variant (by type design). Only optional
+            // maxLength and required are supported; otherwise it is an unrestricted
+            // z.string().
             let schema = z.string();
             if (field.maxLength)
                 schema = schema.max(field.maxLength);
@@ -148,13 +150,13 @@ export function fieldToZod(field, currencies, opts = {}) {
             if (field.default !== undefined) {
                 // Untouched <select> sends "" too; with a default that maps to the
                 // default (same semantics as undefined) instead of the invalid-value
-                // rejection from #1702. A field with a default is never "unset" —
+                // rejection. A field with a default is never "unset" —
                 // true on both insert AND update, so this branch (and its "" → default
                 // mapping) fires regardless of applyDefaults; only the `.default(...)`
                 // schema-level fallback for OMITTED input is update-gated below.
                 // `null` maps the same way: the no-default branch below normalizes
                 // an untouched select to null, and a client that reuses that value
-                // against a since-defaulted field must not get rejected either.
+                // against a defaulted field must not get rejected either.
                 const mapped = z.preprocess((value) => (value === "" || value === null ? field.default : value), enumSchema);
                 return applyDefaults ? mapped.default(field.default) : mapped;
             }
@@ -171,9 +173,9 @@ export function fieldToZod(field, currencies, opts = {}) {
             const [first, ...rest] = field.options;
             if (!first)
                 return z.array(z.string());
-            // `required: true` heißt non-empty — Analogie zu `text`-Field.
-            // Leeres Array wird rejected; das globale `.optional()`-Wrapping
-            // in buildInsertSchema kümmert sich um „darf fehlen".
+            // `required: true` means non-empty, as with a `text` field.
+            // An empty array is rejected; the global `.optional()` wrapping
+            // in buildInsertSchema determines whether the field may be omitted.
             let schema = z.array(z.enum([first, ...rest]));
             if (field.required)
                 schema = schema.min(1);
@@ -209,10 +211,10 @@ export function fieldToZod(field, currencies, opts = {}) {
             return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
         }
         case "bigInt": {
-            // JS-`number`-Round-trip via mode:"number"; sicher bis 2^53.
-            // safe-integer-Cap ist explizit damit ein Caller, der einen
-            // Float reinwirft (z.B. parseFloat-Bug), beim Insert sofort
-            // failed statt silent-Truncation zu kassieren.
+            // JS-`number` round-trip via mode:"number"; exact up to 2^53.
+            // The safe-integer cap ensures that a caller passing a float (for example,
+            // due to a parseFloat bug) fails immediately at insert instead of being
+            // silently truncated.
             const schema = z.number().int().safe();
             return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
         }
@@ -267,8 +269,8 @@ export function fieldToZod(field, currencies, opts = {}) {
             });
         }
         case "jsonb": {
-            // Free-form jsonb — keys sind tenant-/runtime-defined. Validation
-            // passthrough: any plain object passt durch.
+            // Free-form jsonb — keys are tenant-/runtime-defined. Validation
+            // passes through any plain object.
             return z.record(z.string(), z.unknown());
         }
         case "date": {
@@ -276,26 +278,26 @@ export function fieldToZod(field, currencies, opts = {}) {
             return withDateBounds(schema, field.min, field.max);
         }
         case "timestamp": {
-            // Wenn locatedBy gesetzt: Wall-Clock OHNE Offset (ISO-Datetime ohne `Z`).
-            // Sonst: ISO-UTC-Datetime (mit `Z`). Beide werden über z.iso.datetime
-            // gegen das ISO-8601-Schema validiert; die Präzision (mit/ohne Offset)
-            // hängt von locatedBy ab.
+            // When locatedBy is set: wall-clock time without an offset (ISO datetime
+            // without `Z`). Otherwise: ISO UTC datetime (with `Z`). Both are validated
+            // against the ISO-8601 schema through z.iso.datetime; precision (with or
+            // without an offset) depends on locatedBy.
             const schema = field.locatedBy !== undefined ? z.iso.datetime({ local: true }) : z.iso.datetime();
             return withDateBounds(schema, field.min, field.max);
         }
         case "tz": {
-            // IANA-Zonenname, validiert gegen die Runtime-Zonenliste
-            // (isValidIanaTimeZone). Ein ungültiger Name failt hier am
-            // Write-Boundary statt erst später in ctx.tz.parse / Temporal.
+            // IANA time-zone name, validated against the runtime's zone list
+            // (isValidIanaTimeZone). An invalid name fails at the write boundary
+            // instead of later in ctx.tz.parse / Temporal.
             return z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
         }
         case "locatedTimestamp": {
-            // Combined Wall-Clock+TZ Object. Beim Write akzeptieren wir entweder
-            // { at, tz } (typisch UI-Form, utc wird berechnet) oder { utc, tz }
-            // (typisch Server-zu-Server, at wird berechnet). Beim Read liefert
-            // der Read-Wrapper alle drei Felder (siehe Phase D in MIGRATION.md).
+            // Combined wall-clock and time-zone object. On write, either
+            // { at, tz } (typical for a UI form, with utc calculated) or { utc, tz }
+            // (typical for server-to-server communication, with at calculated) is
+            // accepted. On read, the read wrapper provides all three fields.
             //
-            // Hier nur die Schema-Garantie: mindestens tz + (at ODER utc).
+            // The schema guarantees only tz plus at least one of at or utc.
             const at = z.iso.datetime({ local: true });
             const tz = z.string().refine(isValidIanaTimeZone, { message: "invalid IANA time zone" });
             const utc = z.iso.datetime();
@@ -322,11 +324,12 @@ export function fieldToZod(field, currencies, opts = {}) {
             return field.maxCount === undefined ? ids : ids.max(field.maxCount);
         }
         case "reference":
-            // Tier 2.7e-3: Validiert UUID-shape. Existenz-Check der Reference
-            // (Row im referenced Table existiert + Tenant-Scope) ist Server-
-            // side-Verantwortung im Handler / Foreign-Key-Constraint, nicht
-            // im Schema-Validator (würde sonst Round-trip zur DB beim Parse).
-            // Multi-Mode (Tier 2.7e-Multi): Array von UUIDs.
+            // Validates the UUID shape. Checking that the reference exists
+            // (the row exists in the referenced table and belongs to the tenant) is
+            // the handler / foreign-key constraint's responsibility, not the schema
+            // validator's; checking it here would require a database round trip during
+            // parsing.
+            // Multi-mode accepts an array of UUIDs.
             return field.multiple === true ? z.array(z.uuid()) : z.uuid();
         default:
             assertUnreachable(field, "field type");
@@ -342,8 +345,7 @@ export function fieldToZod(field, currencies, opts = {}) {
 // fails the check even if the raw minor-unit amounts happen to match.
 //
 // Known limitation: compares against rounded `derived` cells, i.e.
-// "sum-of-rounded" not "round-of-sum" (kumiko-framework#1866). Follow-up
-// for a computed, read-only sibling total: kumiko-framework#1873.
+// "sum-of-rounded" not "round-of-sum".
 // kumiko-lint-ignore complexity-budget currency-equality check on sibling money payloads
 function applyTotalsMatchRefinements(entity, schema) {
     let result = schema;
@@ -360,7 +362,7 @@ function applyTotalsMatchRefinements(entity, schema) {
                     continue;
                 // One side of a totalsMatch pair without the other → reject. Update
                 // payloads only carry `changes`, so omitting the sibling would otherwise
-                // silently leave sum ≠ total (fw#1841).
+                // silently leave sum ≠ total.
                 if (rawRows === undefined || siblingRaw === undefined) {
                     ctx.addIssue({
                         code: "custom",
@@ -478,7 +480,7 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // sends only `{ title }` means "only change title"; zod defaults would
         // silently inject default values for every omitted field and clobber
         // existing data via the event-store-executor's `changes` payload.
-        // The field is passed through un-stripped (unlike before fw#1703) so
+        // The field is passed through un-stripped so
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.

package/dist/engine/screen-filter-ops.js

@@ -1,18 +1,16 @@
-// Screen-Filter (Tier 2.7c) — Op-vs-Field-Type-Compatibility.
+// Screen-Filter — operator-to-field-type compatibility.
 //
-// Wer darf was filtern?
-//   - text/select/multiSelect: nur equality-Ops (eq, ne, in). lt/gt
-//     auf Strings ist semantisch fast immer Tippfehler (lexicographic
-//     compare nutzt der Author selten bewusst); Author kann den
-//     Filter dann einfach nicht setzen.
-//   - boolean: eq, ne (in/lt/gt sinnlos für 2-Werte-Type).
-//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 7
-//     Ops — die Felder sind natürlich vergleichbar.
+// Allowed operators depend on the field type:
+//   - text/select/multiSelect: equality operators only (eq, ne, in). lt/gt
+//     on strings are usually accidental; authors can simply omit the filter.
+//   - boolean: eq, ne (in/lt/gt are meaningless for a two-value type).
+//   - number/money/decimal/date/timestamp/locatedTimestamp: all 7 operators,
+//     because these fields are naturally comparable.
 //
-// Boot-Validator nutzt diese Map um Author-Fehler früh zu fangen
-// ("filter mit op:lt auf einem text-Feld" → Boot-Fail). Erweitert sich
-// transparent: neuer Field-Type → hier eintragen + sortable/filterable-
-// Flag im Type-Def, sonst lehnt der Validator das Field generell ab.
+// The boot validator uses this map to catch authoring errors early
+// ("filter with op:lt on a text field" → boot failure). When adding a field
+// type, add it here and set its sortable/filterable flag in the type definition;
+// otherwise the validator rejects the field entirely.
 const EQUALITY_ONLY = ["eq", "ne", "in"];
 const COMPARABLE = [
     "eq",
@@ -39,17 +37,16 @@ export function getAllowedFilterOps(field) {
         case "timestamp":
         case "locatedTimestamp":
             return COMPARABLE;
-        // tz/embedded/file/image/files/images: nicht filterbar — Author
-        // kann das Feld nicht als filterable: true markieren (Boot-
-        // Validator weist `filterable: true` auf den Types ohnehin schon
-        // ab, weil das Flag dort gar nicht im Type-Def steht).
+        // tz/embedded/file/image/files/images: not filterable — authors cannot
+        // mark the field as filterable: true because the boot validator already
+        // rejects `filterable: true` for these types; the flag is not present in
+        // their type definitions.
         default:
             return [];
     }
 }
-// Author hat das Feld als filterable markiert? Tz/Embedded/File-Types
-// haben das Flag gar nicht im Type-Def, also fangen wir das per
-// `"filterable" in field`-Narrow ab.
+// If an author marked the field as filterable, catch types without that
+// flag in their type definition with the `"filterable" in field` narrowing.
 export function isFieldFilterable(field) {
     return "filterable" in field && field.filterable === true;
 }