@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/registry-ingest.js

@@ -16,16 +16,16 @@ export function populateFeatureCore(state, feature) {
             throw new Error(`Duplicate entity: "${name}" (registered by multiple features)`);
         }
         state.entityMap.set(name, entity);
-        const physical = resolveTableName(name, entity, feature.name);
+        const physical = resolveTableName(name, entity, undefined);
         const clash = state.physicalTableOwners.get(physical);
         if (clash?.kind === "store") {
             throw new Error(`Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
                 `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) {