@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

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;
 }

package/dist/engine/screen-helpers.js

@@ -1,3 +1,5 @@
+import { createFallbackLogger } from "../logging/utils.js";
+const log = createFallbackLogger("kumiko");
 // Entity name the renderer gives the synthesized entity of an actionForm, secretMint or confirm
 // step. It is not registered, so nothing server-side may treat it as a real entity.
 export const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
@@ -71,7 +73,7 @@ export function isWriteFormEditSection(section) {
 }
 // Union of both sources, unlike the boot-validator's either-or flattening: that
 // one runs after the fields-XOR-groups check, collectors run without it and must
-// not drop a source (fw#2986).
+// not drop a source.
 export function sectionFieldSpecs(section) {
     return [...(section.fields ?? []), ...(section.groups?.flatMap((group) => group.fields) ?? [])];
 }
@@ -90,8 +92,7 @@ export function normalizeListColumn(c) {
         process.env.NODE_ENV !== "production" &&
         col.renderer !== undefined &&
         typeof col.renderer === "function") {
-        // biome-ignore lint/suspicious/noConsole: dev-only warning
-        console.warn(`[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`);
+        log.warn(`normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`);
     }
     return col;
 }

package/dist/engine/state-machine.d.ts

@@ -1,14 +1,14 @@
 /**
  * Type-safe transition graph. Wraps the underlying Map so callers don't
  * accidentally fall into the `transitions[from]?.includes(to)` footgun
- * (Object-Index-Access auf einer Map returnt undefined und der ganze
- * Check kollabiert silently). Stattdessen forciert die API explizite
- * Methoden — kein Map-shape mehr extern sichtbar.
+ * (indexing a Map like an object returns undefined and silently breaks the
+ * entire check). The API therefore enforces explicit methods, with no Map
+ * shape exposed externally.
  *
  * - `canTransition(from, to)` → boolean
- * - `allowedFrom(from)` → readonly string[] (leer wenn `from` unbekannt
- *   oder terminaler Zustand)
- * - `assertTransition(from, to)` → wirft UnprocessableError(invalid_transition)
+ * - `allowedFrom(from)` → readonly string[] (empty when `from` is unknown
+ *   or terminal)
+ * - `assertTransition(from, to)` → throws UnprocessableError(invalid_transition)
  */
 export type TransitionGraph<TStates extends string = string> = {
     readonly canTransition: (from: TStates, to: TStates) => boolean;
@@ -17,8 +17,8 @@ export type TransitionGraph<TStates extends string = string> = {
 };
 /**
  * Defines allowed state transitions. Returns a typed graph (see
- * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
- * type-error statt silent undefined.
+ * TransitionGraph), not a Map. This makes `transitions[x]` access a
+ * type error instead of silently returning undefined.
  */
 export declare function defineTransitions<const TMap extends Record<string, readonly string[]>>(map: TMap): TransitionGraph<keyof TMap & string>;
 /**
@@ -26,9 +26,9 @@ export declare function defineTransitions<const TMap extends Record<string, read
  * reason="invalid_transition" if not — the 422 status lets the client
  * distinguish a logical rejection from a validation or auth failure.
  *
- * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
- * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
- * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
- * idiomatische API für neuen Code.
+ * Convenience wrapper around `transitions.assertTransition(from, to)` —
+ * it exists because existing callers use the `guardTransition(graph, ...)`
+ * form. Both are supported; the graph method is the idiomatic API for new
+ * code.
  */
 export declare function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void;

package/dist/engine/state-machine.js

@@ -1,8 +1,8 @@
 import { buildInvalidTransitionDetails, FrameworkReasons, UnprocessableError, } from "../errors/index.js";
 /**
  * Defines allowed state transitions. Returns a typed graph (see
- * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
- * type-error statt silent undefined.
+ * TransitionGraph), not a Map. This makes `transitions[x]` access a
+ * type error instead of silently returning undefined.
  */
 export function defineTransitions(map) {
     const internal = new Map();
@@ -17,7 +17,7 @@ export function defineTransitions(map) {
         },
         assertTransition: (from, to) => {
             const set = internal.get(from);
-            // skip: erlaubter Übergang — kein Throw, fall through.
+            // skip: allowed transition — no throw; fall through.
             if (set?.has(to) === true)
                 return;
             const allowed = set ? [...set] : [];
@@ -33,10 +33,10 @@ export function defineTransitions(map) {
  * reason="invalid_transition" if not — the 422 status lets the client
  * distinguish a logical rejection from a validation or auth failure.
  *
- * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
- * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
- * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
- * idiomatische API für neuen Code.
+ * Convenience wrapper around `transitions.assertTransition(from, to)` —
+ * it exists because existing callers use the `guardTransition(graph, ...)`
+ * form. Both are supported; the graph method is the idiomatic API for new
+ * code.
  */
 // @wrapper-known semantic-alias
 export function guardTransition(transitions, from, to) {

package/dist/engine/steps/_resolver-utils.js

@@ -13,14 +13,15 @@
 // was needed to satisfy TS narrowing on a property-access; passing the
 // arg through a function-call achieves the same narrowing trivially via
 // the function-parameter binding.
-//
-// Followup #10 (closed at the M.1.6 cleanup-pass).
+function isResolverFunction(arg) {
+    return typeof arg === "function";
+}
 /**
  * Resolve a required StepResolver — either a static value or a function.
  * Throws if `arg` is undefined; caller must guarantee presence.
  */
 export function resolveRequired(arg, ctx) {
-    if (typeof arg === "function") {
+    if (isResolverFunction(arg)) {
         return arg(ctx);
     }
     return arg;

package/dist/engine/steps/for-each.js

@@ -24,12 +24,12 @@
 // ```
 //
 // M.1.6 supports `concurrency: 1` only (sequential). Concurrent
-// execution (Promise.all-style) is Followup #12 — TX-sharing,
+// execution (Promise.all-style) requires its own audit cycle: TX-sharing,
 // AbortSignal-cancellation, and lifecycle-hook ordering each warrant
-// their own audit cycle (Q16).
+// separate review.
 //
-// Q15: `as` is required — without it, the current item is unreachable
-// from the sub-pipeline's resolvers. Q12: r.step.return inside `do` is
+// `as` is required — without it, the current item is unreachable
+// from the sub-pipeline's resolvers. `r.step.return` inside `do` is
 // rejected at build time (would trigger the discriminated-union
 // TData-Inference trap).
 import { defineStep } from "../define-step.js";

package/dist/engine/steps/unsafe-projection-delete.js

@@ -6,7 +6,7 @@
 // r.requires.projection allowlist, must NOT be a registered
 // r.entity-aggregate-table. Skips the same set of framework-protections
 // (lifecycle hooks, field-access, audit-trail, etc.) — see
-// step-vocabulary.md "Was unsafeProjection.* überspringt".
+// step-vocabulary.md "What unsafeProjection.* skips".
 //
 // Convention (not enforced): most legitimate read-side deletions are
 // downstream of an aggregate event (e.g. delete-user → cascading

package/dist/engine/steps/unsafe-projection-upsert.js

@@ -2,13 +2,13 @@
 //
 // Idempotent on the supplied conflict-key columns (typically the
 // natural key + tenantId). Skips lifecycle hooks, field-access,
-// crypto-shredding, schema-versioning, audit-trail, read-access-log.
-// See "Was unsafeProjection.* überspringt" in
+// crypto-shredding, schema-versioning, audit-trail, and read-access-log.
+// See "What unsafeProjection.* skips" in
 // kumiko-platform/docs/archive/plans/architecture/intern/step-vocabulary.md.
 //
 // Use only on tables explicitly declared via r.requires.projection in
-// the owning feature. Aggregate-tables (registered via r.entity) are
-// rejected by boot-validation — domain mutation MUST go through
+// the owning feature. Aggregate tables (registered via r.entity) are
+// rejected by boot validation — domain mutation MUST go through
 // r.step.aggregate.*.
 import { extractTableName } from "../../db/index.js";
 import { executeRawQuery } from "../../db/queries/raw-sql.js";

package/dist/engine/steps/wait-for-event.js

@@ -16,10 +16,10 @@
 // resultKey is `args.event` itself (the branded event-type string) rather
 // than a new `name` argument — a workflow only ever has one `awaits` entry
 // per event type, so `ctx.steps[awaits.someKey]` is already a unique,
-// intention-revealing handle. resume-run.write.ts (framework#2513 Phase 3b)
-// is the only producer of this key's value: the step itself always
-// suspends (never returns a real result), so a subsequent step only ever
-// sees the matched event's payload after a resume seeds it in.
+// intention-revealing handle. resume-run.write.ts is the only producer of
+// this key's value: the step itself always suspends (never returns a real
+// result), so a subsequent step only ever sees the matched event's payload
+// after a resume seeds it in.
 import { defineStep } from "../define-step.js";
 import { addDuration } from "./_duration-utils.js";
 import { resolveOptional, resolveRequired } from "./_resolver-utils.js";

package/dist/engine/steps/workflow-system-events.js

@@ -15,7 +15,7 @@ const triggerEventRefSchema = z.object({
     aggregateId: z.string(),
     version: z.number().int(),
 });
-// Optional on every step event: runs started before the Q7 fingerprint existed
+// Optional on every step event: runs started before the fingerprint existed
 // have none.
 const stepContext = {
     workflowName: z.string(),
@@ -29,8 +29,8 @@ const WORKFLOW_SYSTEM_EVENT_SCHEMAS = [
         z.object({
             workflowName: z.string(),
             triggerEventType: z.string(),
-            // Current streams reference the trigger event; streams written before
-            // #3474 carry a copy of its payload instead.
+            // Current streams reference the trigger event; older streams carry a copy of
+            // its payload instead.
             triggerEventRef: triggerEventRefSchema.optional(),
             triggerPayload: z.unknown().optional(),
             definitionFingerprint: z.string().optional(),

package/dist/engine/tier-resolver-extension.d.ts

@@ -4,30 +4,32 @@ import type { RegistrarExtensionRegistration } from "./types/config.ts";
 import type { FeatureDefinition, Registry } from "./types/feature.ts";
 import type { TenantId } from "./types/identifiers.ts";
 /**
- * Extension-name unter dem ein tier-resolver-plugin im registry registriert
- * werden muss. Konstante damit `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
- * + framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` typo-resistent
- * gegen den selben Wert prüfen.
+ * Extension name under which a tier-resolver plugin must be registered in the
+ * registry. The constant keeps `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
+ * and the framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` aligned
+ * on the same value, preventing typos.
  */
 export declare const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
 /**
- * Resolver-callback shape: synchron (dispatcher hot-path), per-tenant.
- * Returnt das effective feature-Set für den tenant. Implementations sollten
- * einen in-memory cache pflegen + per `r.entityHook` invalidieren.
+ * Resolver callback shape: synchronous (on the dispatcher's hot path), per
+ * tenant. Returns the tenant's effective feature set. Implementations should
+ * maintain an in-memory cache and invalidate it via `r.entityHook`.
  *
- * **System-context convention:** call mit SYSTEM_TENANT_ID erwartet die union
- * aller tier-features (siehe DispatcherOptions.effectiveFeatures doc-block).
+ * **System-context convention:** calls with SYSTEM_TENANT_ID must return the
+ * union of all tier features (see the DispatcherOptions.effectiveFeatures
+ * doc block).
  */
 export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & {
     /**
-     * Optionaler Live-Trial-Gate, vom dispatcher-feature-gate NUR konsultiert
-     * wenn der synchrone Resolver ein Feature als disabled meldet. Liest das
-     * Signup-Datum des Tenants live (tenant.inserted_at) und returnt true wenn
-     * der Tenant im Trial-Fenster ist UND das Feature zum Trial-Tier gehört.
-     * Async + nicht im Boot-Cache, weil der Trial zeit-abgeleitet ist (ändert
-     * sich zwischen Requests). Konsultiert an 3 Stellen: den 2 Dispatch-Gate-
-     * Aufrufstellen (checkFeatureEnabled) UND ctx.hasFeature im Handler-Body
-     * (fällt darauf zurück, wenn der synchrone Feature-Set-Check negativ ist).
+     * Optional live-trial gate, consulted by the dispatcher feature gate ONLY
+     * when the synchronous resolver reports a feature as disabled. Reads the
+     * tenant's signup date live (tenant.inserted_at) and returns true when the
+     * tenant is within the trial window AND the feature belongs to the trial
+     * tier. It is async and not part of the boot cache because the trial is
+     * time-dependent and can change between requests. Consulted at three
+     * locations: the two dispatch-gate call sites (checkFeatureEnabled) AND
+     * ctx.hasFeature in the handler body (as a fallback when the synchronous
+     * feature-set check is negative).
      */
     readonly trialGate?: TrialGate;
 };
@@ -36,10 +38,10 @@ export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<str
  */
 export type TrialGate = (tenantId: TenantId, featureName: string) => Promise<boolean>;
 /**
- * Plugin-shape für tier-resolver-extension. Plugins implementieren `build`
- * als boot-time factory: kriegen `db` + `registry` (post-stack-setup),
- * laden initial cache aus DB, returnen den synchronen resolver-callback
- * (optional mit angehängtem `trialGate`).
+ * Plugin shape for the tier-resolver extension. Plugins implement `build`
+ * as a boot-time factory: they receive `db` + `registry` (after stack setup),
+ * load the initial cache from the database, and return the synchronous
+ * resolver callback, optionally with an attached `trialGate`.
  */
 export type TierResolverPlugin = {
     readonly build: (deps: {
@@ -49,13 +51,13 @@ export type TierResolverPlugin = {
     }) => Promise<EffectiveFeaturesResolver>;
 };
 /**
- * Scan a composed feature-list for a `tenantTierResolver`-extension usage.
- * Single plugin assumption — multiple wären ambiguous (welcher resolver
- * gewinnt). Memory `feedback_no_options_without_need`: kein multi-merge-
- * pattern bis es echten Use-Case gibt.
+ * Scans a composed feature list for a `tenantTierResolver` extension usage.
+ * Only one plugin is supported because multiple plugins would be ambiguous:
+ * it would be unclear which resolver should win. No multi-merge pattern is
+ * needed until there is a real use case.
  *
- * Geteilter helper für runDevApp + runProdApp damit der Pickup-Pfad
- * bit-identisch ist (drift-resistent).
+ * Shared by runDevApp + runProdApp so the pickup path remains byte-for-byte
+ * identical and cannot drift.
  */
 /** Narrows a registration's untyped `options` bag to the tier-resolver
  *  plugin shape — the only thing every implementation must provide is the

package/dist/engine/tier-resolver-extension.js

@@ -1,40 +1,40 @@
-// Sprint-8a Tier-Composition: framework-extension-point für per-tenant
+// Tier composition: framework extension point for per-tenant
 // effective-feature resolution.
 //
-// **Pattern (analog mail-foundation / file-foundation):** ein Feature
-// declares `r.extendsRegistrar("tenantTierResolver")` und plugins
-// implementieren via `r.useExtension("tenantTierResolver", "id", { build })`.
+// **Pattern (analogous to mail-foundation / file-foundation):** a feature
+// declares `r.extendsRegistrar("tenantTierResolver")`, and plugins
+// implement it via `r.useExtension("tenantTierResolver", "id", { build })`.
 //
-// **Auto-wiring im Framework:** runDevApp + runProdApp scannen das registry
-// nach genau diesem extension-name. Wenn ein plugin gefunden ist UND der
-// App-Author nicht selbst eine `effectiveFeatures`-callback gesetzt hat,
-// wird `plugin.build({ db, registry })` einmalig in onAfterSetup aufgerufen.
-// Der returned callback landet als `effectiveFeatures` im dispatcher.
+// **Framework auto-wiring:** runDevApp + runProdApp scan the registry
+// for this exact extension name. If a plugin is found AND the app author
+// has not set an `effectiveFeatures` callback, `plugin.build({ db, registry })`
+// is called once in onAfterSetup. The returned callback becomes
+// `effectiveFeatures` in the dispatcher.
 //
-// **Warum dieser Pattern:** App-Author mountet `createTierEngineFeature(opts)`
-// und das war's — kein Late-Bound-Holder im run-config, kein
-// effectiveFeatures-callback wiren. Das Framework macht den Late-Bound-Trick
-// intern. Memory `feedback_alles_ist_ein_feature`: Tier-Composition ist
-// ein Feature, nicht ein Subsystem mit App-spezifischem Wiring.
+// **Why this pattern:** the app author mounts
+// `createTierEngineFeature(opts)` and is done—no late-bound holder in the
+// run config and no need to wire an effectiveFeatures callback. The framework
+// handles the late-binding internally. Tier composition is a feature, not a
+// subsystem with app-specific wiring.
 //
-// **Apps ohne tier-engine:** wenn keine plugin registriert ist, framework
-// macht nichts — `effectiveFeatures` bleibt undefined, alle features sind on.
+// **Apps without a tier engine:** if no plugin is registered, the framework
+// does nothing—`effectiveFeatures` remains undefined, and all features are on.
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 /**
- * Extension-name unter dem ein tier-resolver-plugin im registry registriert
- * werden muss. Konstante damit `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
- * + framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` typo-resistent
- * gegen den selben Wert prüfen.
+ * Extension name under which a tier-resolver plugin must be registered in the
+ * registry. The constant keeps `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
+ * and the framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` aligned
+ * on the same value, preventing typos.
  */
 export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
 /**
- * Scan a composed feature-list for a `tenantTierResolver`-extension usage.
- * Single plugin assumption — multiple wären ambiguous (welcher resolver
- * gewinnt). Memory `feedback_no_options_without_need`: kein multi-merge-
- * pattern bis es echten Use-Case gibt.
+ * Scans a composed feature list for a `tenantTierResolver` extension usage.
+ * Only one plugin is supported because multiple plugins would be ambiguous:
+ * it would be unclear which resolver should win. No multi-merge pattern is
+ * needed until there is a real use case.
  *
- * Geteilter helper für runDevApp + runProdApp damit der Pickup-Pfad
- * bit-identisch ist (drift-resistent).
+ * Shared by runDevApp + runProdApp so the pickup path remains byte-for-byte
+ * identical and cannot drift.
  */
 /** Narrows a registration's untyped `options` bag to the tier-resolver
  *  plugin shape — the only thing every implementation must provide is the