@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/schema-cli.js

@@ -17,8 +17,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolveKmsWiringAsync, } from "./crypto/index.js";
 import { assertUniqueTableNames, assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, findCommentedDropTables, generateMigration, isRetiredFrameworkTable, loadMigrationsFromDir, loadSnapshotJson, readMigrationSqlTexts, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
+import { isEntityTableMeta } from "./db/table-introspection.js";
 import { validateBoot } from "./engine/boot-validator.js";
 import { FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, } from "./engine/extension-names.js";
 import { createRegistry } from "./engine/registry.js";
@@ -75,6 +77,79 @@ function parseValidateBootOptions(raw) {
         ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),
     };
 }
+function tableNameHint(entry) {
+    if (isPlainObject(entry) && typeof entry["tableName"] === "string")
+        return entry["tableName"];
+    return "unknown";
+}
+// Every non-optional top-level property of FeatureDefinition, grouped by the runtime shape the
+// boot validators rely on; a hand-built entry missing one would crash far from the cause.
+const FEATURE_ARRAY_KEYS = [
+    "requires",
+    "optionalRequires",
+    "configSeeds",
+    "extensionUsages",
+    "extensionSelectors",
+    "bootChecks",
+    "referenceData",
+    "configReads",
+    "authClaimsHooks",
+];
+const FEATURE_SET_KEYS = [
+    "requiredProjections",
+    "requiredSteps",
+    "exposedApis",
+    "usedApis",
+];
+const FEATURE_RECORD_KEYS = [
+    "relations",
+    "writeHandlers",
+    "queryHandlers",
+    "streamHandlers",
+    "translations",
+    "configKeys",
+    "jobs",
+    "registrarExtensions",
+    "notifications",
+    "events",
+    "eventMigrations",
+    "handlerEntityMappings",
+    "metrics",
+    "secretKeys",
+    "secretNamespaces",
+    "projections",
+    "multiStreamProjections",
+    "claimKeys",
+    "screens",
+    "navs",
+    "workspaces",
+    "httpRoutes",
+    "webSocketRoutes",
+    "storeTables",
+];
+function isFeatureDefinitionShape(entry) {
+    if (!isPlainObject(entry))
+        return false;
+    return (typeof entry["name"] === "string" &&
+        typeof entry["systemScope"] === "boolean" &&
+        FEATURE_ARRAY_KEYS.every((key) => Array.isArray(entry[key])) &&
+        FEATURE_SET_KEYS.every((key) => entry[key] instanceof Set) &&
+        FEATURE_RECORD_KEYS.every((key) => isPlainObject(entry[key])));
+}
+// FEATURES comes from the app's schema module; one malformed entry would make
+// validateBoot fail with an unrelated error far from the cause, so name the index here.
+function featureDefinitionsOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const definitions = [];
+    for (const [index, entry] of value.entries()) {
+        if (!isFeatureDefinitionShape(entry)) {
+            throw new Error(`FEATURES[${index}] is not a FeatureDefinition (expected an object with a string \`name\`)`);
+        }
+        definitions.push(entry);
+    }
+    return definitions;
+}
 // Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
 // both need ENTITY_METAS (and validate additionally wants FEATURES); this is
 // the one place that enforces "ENTITY_METAS must be an array" so the two
@@ -83,13 +158,20 @@ function parseValidateBootOptions(raw) {
 async function loadSchemaModFromApp(schemaFile) {
     // bun imports TS directly — no spawn needed.
     const mod = await import(__rewriteRelativeImportExtension(schemaFile));
-    if (!Array.isArray(mod["ENTITY_METAS"])) {
+    const entityMetas = mod["ENTITY_METAS"];
+    if (!Array.isArray(entityMetas)) {
         throw new Error(`Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`);
     }
-    const entityMetas = mod["ENTITY_METAS"];
-    assertUniqueTableNames(entityMetas);
+    const validMetas = [];
+    for (const [index, entry] of entityMetas.entries()) {
+        if (!isEntityTableMeta(entry)) {
+            throw new Error(`Schema file ${schemaFile}: ENTITY_METAS[${index}] is not an EntityTableMeta (table: ${tableNameHint(entry)}).`);
+        }
+        validMetas.push(entry);
+    }
+    assertUniqueTableNames(validMetas);
     return {
-        entityMetas,
+        entityMetas: validMetas,
         features: mod["FEATURES"],
         validateBootOptions: mod["VALIDATE_BOOT_OPTIONS"],
     };
@@ -223,9 +305,9 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 mkdirSync(migrationsDir, { recursive: true });
             writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
             writeSnapshotJson(snapshotPath, result.snapshot);
-            // Rebuild-Marker nur für inkrementelle Migrationen — die Init-Migration
-            // (prevSnapshot===null) legt nur Tabellen an, es gibt keine historischen
-            // Events zum Replayen.
+            // Rebuild markers are written only for incremental migrations — the initial
+            // migration (prevSnapshot===null) only creates tables, so there are no historical
+            // events to replay.
             const rebuildTables = prevSnapshot === null ? [] : rebuildTablesFromDiff(result.diff);
             writeRebuildMarker(migrationsDir, result.filename, rebuildTables);
             out.log("");
@@ -269,7 +351,6 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 out.err(`  ${e instanceof Error ? e.message : String(e)}`);
                 return 1;
             }
-            const mod = { FEATURES: schemaMod.features };
             let ok = true;
             // 1. Schema drift — compute the diff, never write.
             const metas = schemaMod.entityMetas;
@@ -299,9 +380,21 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 out.err("    Fix: `kumiko-schema generate <name>`, then commit the migration.");
             }
             // 2. Boot validity — needs the composed feature set.
-            if (Array.isArray(mod.FEATURES)) {
+            let bootFeatures;
+            let bootFeaturesError;
+            try {
+                bootFeatures = featureDefinitionsOf(schemaMod.features);
+            }
+            catch (e) {
+                bootFeaturesError = e instanceof Error ? e.message : String(e);
+            }
+            if (bootFeaturesError !== undefined) {
+                ok = false;
+                out.err(`  ✗ boot: ${bootFeaturesError}`);
+            }
+            else if (bootFeatures) {
                 try {
-                    validateBoot(mod.FEATURES, {
+                    validateBoot(bootFeatures, {
                         ...parseValidateBootOptions(schemaMod.validateBootOptions),
                         env: withFileStoragePresence(process.env),
                     });
@@ -350,7 +443,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                     // replayMigrationsDir fail-loud's on a table-DDL statement it can't
                     // parse — that must surface as a normal ✗ line like every other
                     // check here, not a raw stack trace that kills the process before
-                    // any later check (or the Fix: help) ever runs (framework#1535).
+                    // any later check (or the Fix: help) ever runs.
                     ok = false;
                     out.err(`  ✗ migration-content: ${e instanceof Error ? e.message : String(e)}`);
                     out.err("    Fix: a statement in a migration file isn't recognizable to the replay parser — extend the parser's recognized patterns, or reword the migration to one it understands.");
@@ -372,11 +465,12 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             let wiring;
             try {
                 const result = await runMigrationsFromDir(db, migrationsDir);
-                // Framework-Infra-Tabellen (event-store + pipeline-state) — die erfasst
-                // `generate` nicht (nur Entity-read-Tabellen). Bestehende DBs haben sie
-                // aus dem legacy-drizzle-Fundament; eine Greenfield-DB (erste App ohne
-                // Cutover) hätte sonst kein kumiko_events → runProdApp-Boot scheitert.
-                // Alle drei sind idempotent (tableExists-Gate), also no-op für Bestands-DBs.
+                // Framework infrastructure tables (event store + pipeline state) are not captured by
+                // `generate`, which handles only entity read tables. Existing databases have them
+                // from the legacy-drizzle foundation; without them, a greenfield database (the
+                // first app without a cutover) would lack kumiko_events and runProdApp would fail
+                // during boot. All three are idempotent (tableExists-gated), so they are no-ops for
+                // existing databases.
                 await createEventsTable(db);
                 await createEventConsumerStateTable(db);
                 await createProjectionStateTable(db);
@@ -400,14 +494,14 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 // (kumiko_pending_rebuilds) survives a failed/crashed rebuild from an
                 // earlier apply, so a later apply with zero new migrations still must
                 // retry it — otherwise a failed rebuild is silently never retried,
-                // since the migration itself is already tracked applied (#2464).
+                // since the migration itself is already tracked applied.
                 if (options.features) {
                     // A rebuild replays applyEntityEvent, which computes bidx columns from
                     // configureBlindIndexKey/configurePiiSubjectKms — both boot-injected by
                     // run{Prod,Dev}App but never by this standalone CLI (the migrate-db
                     // initContainer). Without wiring them here, a rebuild would silently
                     // null out bidx columns and, for ciphertext, throw only once it hits
-                    // the row (fw#3091).
+                    // the row.
                     wiring = await resolveKmsWiringAsync(process.env, {
                         logPrefix: "[kumiko schema apply]",
                         log: out.log,
@@ -485,10 +579,10 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             const local = loadMigrationsFromDir(migrationsDir);
             const { db, close } = createDbConnection({ url: dbUrl });
             try {
-                // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table
-                // fehlt = "nichts applied". Connection-/Permission-Fehler dagegen
-                // sollen NICHT geschluckt werden (False-pending verschleiert das Problem) —
-                // tableExists prüft gezielt nur Existenz, alles andere propagiert.
+                // On a fresh database where `kumiko schema apply` has never run, the tracking table is
+                // absent, which means "nothing applied". Connection and permission errors must not
+                // be swallowed (false pending results would hide the problem) — tableExists checks
+                // only for existence, while all other errors propagate.
                 const trackingExists = await tableExists(db, "_kumiko_migrations");
                 const applied = trackingExists
                     ? new Set((await fetchAppliedMigrations(db)).map((a) => a.id))

package/dist/search/index.js

@@ -1,7 +1,7 @@
-// Meilisearch-Adapter lebt im Sub-Path-Export `@cosmicdrift/kumiko-framework/search/meilisearch`.
-// Damit lädt der Main-Barrel keinen Meilisearch-Client beim bloßen Anfassen
-// von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
-// Client-Code nicht mit rein.
+// The Meilisearch adapter is exposed through the subpath export
+// `@cosmicdrift/kumiko-framework/search/meilisearch`. This keeps the main barrel from loading a
+// Meilisearch client when consumers only use SearchAdapter types, so apps that do not use
+// Meilisearch do not pull in the client code.
 export { collectSearchableFieldNames, configureTenantSearchIndex, } from "./configure-tenant-index.js";
 export { deriveSearchAdapterConfig } from "./derive-search-adapter-config.js";
 export { createInMemorySearchAdapter } from "./in-memory-adapter.js";

package/dist/search/purge-subject.js

@@ -1,4 +1,4 @@
-// Purge derived search documents for an erased PII subject (#1610).
+// Purge derived search documents for an erased PII subject.
 //
 // After kms.eraseKey the projection/event ciphertext is unreadable, but Meili
 // still holds the plaintext that createSearchEventConsumer decrypted into the
@@ -152,7 +152,7 @@ subject) {
             if (declaredFields.length === 0)
                 continue;
             const tableName = resolveTableName(entityName, entity, undefined);
-            // Same post-eraseKey hazard as nullBlindIndexesForSubject (fw#2550):
+            // Same post-eraseKey hazard as nullBlindIndexesForSubject:
             // a mounted feature without its migration must not abort the purge
             // (and the audit event after it).
             if (!(await tableExists(db, tableName)))
@@ -178,13 +178,12 @@ subject) {
     for (const [tenantId, items] of byTenant) {
         if (items.length === 0)
             continue;
-        const tid = tenantId;
         if (search.removeBatch) {
-            await search.removeBatch(tid, items);
+            await search.removeBatch(tenantId, items);
         }
         else {
             for (const item of items) {
-                await search.remove(tid, item.entityType, item.entityId);
+                await search.remove(tenantId, item.entityType, item.entityId);
             }
         }
     }

package/dist/search/reindex-entity.js

@@ -1,5 +1,5 @@
 // One-time backfill for entities that only got `searchable: true` after rows
-// already existed (#1206). buildSearchDocument() only runs on the write path
+// already existed. buildSearchDocument() only runs on the write path
 // (createSearchEventConsumer, system-hooks.ts) — pre-existing rows never
 // pass through it, so they stay unfindable until their next write. This
 // re-derives a SearchDocument straight from the read-table row for every
@@ -47,12 +47,8 @@ async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenan
     // calls searchAdapter.remove()) — resurrecting them here would make
     // erased entities findable again.
     const deletedFilter = entity.softDelete === true ? `AND ${quoteIdent("is_deleted")} IS NOT TRUE` : "";
-    const result = {
-        scannedRows: 0,
-        indexedRows: 0,
-        wouldIndexRows: 0,
-        failures: [],
-    };
+    const failures = [];
+    const result = { scannedRows: 0, indexedRows: 0, wouldIndexRows: 0, failures };
     let lastId;
     // Whether a searchable field lacks a matching read-table column depends
     // only on the table's column set (rowToState/Object.hasOwn), not on any
@@ -69,11 +65,12 @@ async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenan
         WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter} ${afterLastId}
         ORDER BY ${quoteIdent("id")} ASC
         LIMIT $2`, lastId === undefined ? [tenantId, batchSize] : [tenantId, batchSize, lastId]);
-        if (rows.length === 0)
+        const [firstRow] = rows;
+        if (firstRow === undefined)
             break;
         if (uncheckedSchema) {
             uncheckedSchema = false;
-            const sampleState = rowToState(rows[0], fieldNames);
+            const sampleState = rowToState(firstRow, fieldNames);
             const unmappedField = searchableFields.find((fieldName) => !(fieldName in sampleState));
             if (unmappedField !== undefined) {
                 throw new Error(`reindexEntity: searchable field "${unmappedField}" is not mappable from read-table ` +

package/dist/time/boot-tz-warning.d.ts

@@ -1,5 +1,5 @@
 /**
- * Warnt einmalig beim Server-Start, wenn die Prozess-TZ nicht UTC ist.
- * Parameter sind für Tests injizierbar. Gibt zurück, ob gewarnt wurde.
+ * Warn once at server startup when the process time zone is not UTC.
+ * Parameters are injectable for tests. Returns whether a warning was emitted.
  */
 export declare function warnIfNonUtcServerTimeZone(resolvedTimeZone?: string, warn?: (message: string) => void): boolean;

package/dist/time/boot-tz-warning.js

@@ -1,17 +1,17 @@
-// Boot-Warnung wenn die Prozess-Uhr nicht in UTC läuft. Der gesamte
-// Server-Code nimmt UTC an (System-TZ ist kein Konzept — siehe timezones.md);
-// eine abweichende Prozess-TZ lässt versehentliche new Date()-Pfade
-// lokal-abhängig brechen ("grün in UTC-CI, kaputt in Berlin-Prod"). Soft:
-// nicht-UTC ist in Dev legitim, daher Warnung statt Boot-Fehler.
+// Warn at boot when the process time zone is not UTC. All server code assumes UTC
+// (the system time zone is not a framework concept); a different process time zone
+// can make accidental new Date() paths behave differently locally ("green in UTC-CI,
+// broken in Berlin production"). This is a soft check: non-UTC is legitimate in
+// development, so warn instead of failing boot.
 function resolvedServerTimeZone() {
     return Intl.DateTimeFormat().resolvedOptions().timeZone;
 }
 /**
- * Warnt einmalig beim Server-Start, wenn die Prozess-TZ nicht UTC ist.
- * Parameter sind für Tests injizierbar. Gibt zurück, ob gewarnt wurde.
+ * Warn once at server startup when the process time zone is not UTC.
+ * Parameters are injectable for tests. Returns whether a warning was emitted.
  */
 export function warnIfNonUtcServerTimeZone(resolvedTimeZone = resolvedServerTimeZone(), 
-// biome-ignore lint/suspicious/noConsole: boot-time warning, no logger wired this early
+// biome-ignore lint/suspicious/noConsole: runs before any logger exists; the default is the only console sink
 warn = console.warn) {
     // GMT and Etc/UTC are UTC-equivalent (no offset, no DST) — TZ=GMT is a
     // legitimate way to pin a process to UTC and must not trip this warning.

package/dist/time/iana.js

@@ -1,13 +1,13 @@
-// IANA-Zonenname-Validierung. Intl.supportedValuesOf("timeZone") liefert nur
-// KANONISCHE Namen — gültige Aliase wie "US/Pacific", "GMT", "Etc/UTC" fehlen
-// darin, obwohl Intl.DateTimeFormat, Temporal und ctx.tz.parse sie alle
-// klaglos akzeptieren. Intl.DateTimeFormat selbst ist aber case-INSENSITIVE
-// ("europe/berlin" resolved klaglos zu "Europe/Berlin") — ein reines
-// try/catch würde also Tippfehler in der Groß-/Kleinschreibung durchlassen.
-// Der exakte Vergleich mit resolvedOptions().timeZone schließt das: ein
-// gültiger kanonischer Name ODER Alias resolved IMMER zu sich selbst
-// (empirisch verifiziert für US/Pacific, GMT, Etc/UTC), ein falsch-gecasteter
-// String resolved zur kanonischen Form und matcht damit nicht mehr exakt.
+// IANA time zone name validation. Intl.supportedValuesOf("timeZone") returns only
+// CANONICAL names — valid aliases such as "US/Pacific", "GMT", and "Etc/UTC" are
+// missing, even though Intl.DateTimeFormat, Temporal, and ctx.tz.parse all
+// accept them without issue. Intl.DateTimeFormat itself is case-INSENSITIVE
+// ("europe/berlin" resolves to "Europe/Berlin") — a simple try/catch would
+// therefore allow capitalization errors through.
+// The exact comparison with resolvedOptions().timeZone prevents this: a valid
+// canonical name OR alias ALWAYS resolves to itself (verified empirically for
+// US/Pacific, GMT, and Etc/UTC), while a incorrectly cased string resolves to
+// the canonical form and no longer matches exactly.
 export function isValidIanaTimeZone(value) {
     try {
         return (new Intl.DateTimeFormat(undefined, { timeZone: value }).resolvedOptions().timeZone === value);

package/dist/time/index.js

@@ -1,13 +1,13 @@
-// Time-Modul: Temporal-Polyfill + ctx.tz Helper.
+// Time module: Temporal polyfill + ctx.tz helper.
 //
-// Aktueller Stand (Iteration 1-4 von Gap-03 in samples/beammycar/MIGRATION.md):
-//   - ensureTemporalPolyfill: installiert Temporal global wenn nötig
-//   - getTemporal: type-safer Zugriff auf globalThis.Temporal
-//   - createTzContext: ctx.tz Factory mit now/today/parse/toLocatedJson/...
-//   - LocatedTimestampJson: API-Boundary-Form { at, tz }
-//   - isValidIanaTimeZone: IANA-Zonennamen-Validierung (type:"tz"-Felder)
-//   - warnIfNonUtcServerTimeZone: Boot-Warnung bei nicht-UTC Prozess-TZ
-//   - GeoTzProvider: optionaler Geo→Zone-Adapter (ctx.tz.fromCoordinates/fromAddress)
+// Provides:
+//   - ensureTemporalPolyfill: installs Temporal globally when needed
+//   - getTemporal: type-safe access to globalThis.Temporal
+//   - createTzContext: ctx.tz factory with now/today/parse/toLocatedJson/...
+//   - LocatedTimestampJson: API-boundary form { at, tz }
+//   - isValidIanaTimeZone: IANA time-zone name validation (type:"tz" fields)
+//   - warnIfNonUtcServerTimeZone: boot warning for a non-UTC process time zone
+//   - GeoTzProvider: optional geo-to-zone adapter (ctx.tz.fromCoordinates/fromAddress)
 export { warnIfNonUtcServerTimeZone } from "./boot-tz-warning.js";
 export { isValidIanaTimeZone } from "./iana.js";
 export { instantToLegacyDate, legacyDateToInstant } from "./legacy-date.js";

package/dist/time/legacy-date.d.ts

@@ -1,5 +1,5 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export declare function instantToLegacyDate(instant: Temporal.Instant): Date;
-/** Gegenrichtung: Date aus einer Fremd-Lib (imapflow INTERNALDATE,
- *  mailparser Date-Header) → Temporal.Instant. */
+/** Converts dates from foreign libraries (imapflow INTERNALDATE,
+ *  mailparser Date headers) to Temporal.Instant. */
 export declare function legacyDateToInstant(date: Date): Temporal.Instant;

package/dist/time/legacy-date.js

@@ -1,15 +1,13 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-// Temporal→Date-Bridge für Lib-APIs die JS-Date verlangen (imapflow
-// search({since}), nodemailer-Header, ...). Gegenstück zur
-// dateToInstant-Richtung der DB-/Event-Store-Boundaries: Feature-Code
-// rechnet in Temporal, konvertiert erst am Aufruf der Fremd-API — der
-// no-date-api-Guard bleibt für Feature-Code scharf, die Konstruktion
-// lebt hier im allowlisteten Time-Layer.
+// Bridge to libraries that require JS `Date` (imapflow
+// search({since}), nodemailer headers, ...). Feature code uses Temporal and
+// converts only at foreign-API boundaries, keeping the no-date-api guard
+// effective outside this allowlisted time layer.
 export function instantToLegacyDate(instant) {
     return new Date(instant.epochMilliseconds);
 }
-/** Gegenrichtung: Date aus einer Fremd-Lib (imapflow INTERNALDATE,
- *  mailparser Date-Header) → Temporal.Instant. */
+/** Converts dates from foreign libraries (imapflow INTERNALDATE,
+ *  mailparser Date headers) to Temporal.Instant. */
 export function legacyDateToInstant(date) {
     return Temporal.Instant.fromEpochMilliseconds(date.getTime());
 }

package/dist/time/polyfill.js

@@ -8,7 +8,7 @@
 //
 // Idempotent: if `globalThis.Temporal` already exists the call is a no-op.
 // The check is the live global — not a sticky module flag — so tests that
-// delete the ambient global (fw#1550) still get it back on the next call.
+// delete the ambient global still get it back on the next call.
 // Re-install assigns the already-resolved module value: re-importing
 // `temporal-polyfill` here would put a polyfill instance on the global while
 // the rest of the code uses the native classes (instanceof mismatch).

package/dist/time/tz-context.d.ts

@@ -3,7 +3,7 @@ export type { Clock, LocatedTimestampJson, TzContext, TzContextOptions, } from "
 /**
  * Factory: creates a TzContext for the current request.
  * Uses the kumiko-types Temporal module export (not globalThis.Temporal) so
- * buildHandlerContext stays ambient-free (fw#1525/#1550).
+ * buildHandlerContext stays ambient-free.
  */
 export declare function createTzContext(options?: TzContextOptions): TzContext;
 /**

package/dist/time/tz-context.js

@@ -25,7 +25,7 @@ const SYSTEM_CLOCK = {
 /**
  * Factory: creates a TzContext for the current request.
  * Uses the kumiko-types Temporal module export (not globalThis.Temporal) so
- * buildHandlerContext stays ambient-free (fw#1525/#1550).
+ * buildHandlerContext stays ambient-free.
  */
 export function createTzContext(options = {}) {
     const tenant = options.tenant ?? "UTC";

package/dist/ui-types/app-schema.js

@@ -1,9 +1,9 @@
-// Client-safe Schema-Types. Wohnen in framework/ui-types statt renderer
-// damit der Server (createKumikoServer / buildAppSchema) sie produzieren
-// kann ohne renderer als Dependency zu ziehen. Renderer + Renderer-Web
-// re-exporten dieselben Symbole — Konsumenten merken den Umzug nicht.
+// Client-safe schema types. Live in framework/ui-types rather than renderer
+// so the server (createKumikoServer / buildAppSchema) can produce them
+// without pulling in renderer as a dependency. Renderer and Renderer-Web
+// re-export the same symbols, so consumers do not notice the move.
 //
-// Pattern: Types fließen "downstream" (framework → renderer → renderer-
-// web), Runtime-Helpers (toAppSchema, isAppSchema) bleiben renderer-side
-// weil das die Layer ist die mit den AppSchemas zur Laufzeit arbeitet.
+// Pattern: types flow "downstream" (framework → renderer → renderer-
+// web); runtime helpers (toAppSchema, isAppSchema) remain renderer-side
+// because that is the layer that works with AppSchemas at runtime.
 export {};

package/dist/ui-types/list-row-meta.js

@@ -39,13 +39,13 @@ export const LIST_ROW_META_REFERENCES = {
 // user:user — the convention QN is a SystemAdmin cross-tenant roster whose
 // `tenants` join must not reach a TenantAdmin, so it stays SystemAdmin-only and
 // the label lookup goes through the member directory instead: own-tenant
-// members for an admin, every user for a SystemAdmin (fw#3107).
+// members for an admin, every user for a SystemAdmin.
 //
 // tenant:tenant — the convention QN, `tenant:query:tenant:list`, is a
 // SystemAdmin-only entity-list handler, so a TenantAdmin got a 403 and every
 // tenant cell fell back to the raw UUID. The label lookup goes through the
 // tenant directory instead: the caller's own tenant for an admin, every
-// tenant for a SystemAdmin (fw#3142).
+// tenant for a SystemAdmin.
 export const REFERENCE_LOOKUP_SOURCES = {
     "user:user": { queryQn: "tenant:query:member-directory", labelKey: "label" },
     "tenant:tenant": { queryQn: "tenant:query:tenant-directory", labelKey: "label" },
@@ -56,10 +56,10 @@ export const REFERENCE_LOOKUP_SOURCES = {
 // otherwise. Keyed by `${refFeature}:${refEntity}` so useReferenceLookup can
 // consult this generically instead of any screen/hook hardcoding an entity
 // name. Central so the label applies to every screen that references this
-// entity, not just delivery-log (fw#2662).
+// entity, not just delivery-log.
 export const SYSTEM_REFERENCE_LABELS = {
     "tenant:tenant": { id: SYSTEM_TENANT_ID, labelKey: "kumiko.reference.system-tenant" },
-    // createdBy on a system write (fw#3103) — SYSTEM_USER_ID is an alias for
+    // createdBy on a system write — SYSTEM_USER_ID is an alias for
     // "no human caller", so read_users never holds a matching row.
     "user:user": {
         id: SYSTEM_USER_ID,

package/dist/upgrade-cli.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { getFlag, getStringFlag, parseArgs } from "./arg-parser.js";
 import { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, } from "./engine/index.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
@@ -96,7 +97,7 @@ export function findFeatureChangelogFiles(featuresDir) {
         // Layout is detected per-package, not guessed from a naming convention:
         // enterprise packages keep changes.json under src/, framework's
         // bundled-features keep it flat. A name-prefix heuristic (e.g. "ai-*")
-        // silently drops packages that don't match it (fw#1605).
+        // silently drops packages that don't match it.
         const srcLayout = join(featuresDir, name, "src", "changes.json");
         const flatLayout = join(featuresDir, name, "changes.json");
         const changelogPath = existsSync(srcLayout) ? srcLayout : flatLayout;
@@ -167,7 +168,7 @@ export function findFeaturesDirs(cwd) {
     // Enterprise repo: packages/<name>/src/changes.json or packages/<name>/changes.json.
     // Detected by presence of changes.json, not a package-name prefix — a
     // prefix heuristic silently stops matching once packages are renamed or a
-    // differently-named package is added (fw#1605). Skipped inside the
+    // differently-named package is added. Skipped inside the
     // framework repo itself (packages/framework present): every package's own
     // changes.json is already collected via findPackageChangelogFiles, and
     // would otherwise get double-counted as one here.
@@ -202,7 +203,7 @@ export function findFeaturesDirs(cwd) {
 // Consumer-facing codemod scripts ship inside the published
 // @cosmicdrift/kumiko-framework package (src/scripts/codemod), not at the
 // git repo root — only the installed package path exists in a consumer's
-// node_modules after a plain npm/bun install (fw#2301).
+// node_modules after a plain npm/bun install.
 export function findCodemodScriptsRoot(repoRoot) {
     const local = join(repoRoot, "packages/framework/src");
     if (existsSync(join(local, CODEMOD_SUBDIR))) {
@@ -213,7 +214,7 @@ export function findCodemodScriptsRoot(repoRoot) {
         if (existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-                if (pkg.name === "@cosmicdrift/kumiko-framework")
+                if (propertyOf(pkg, "name") === "@cosmicdrift/kumiko-framework")
                     return local;
                 // wrong name → fall through
             }
@@ -242,7 +243,7 @@ export function findCodemodScriptsRoot(repoRoot) {
 // absolute paths, symlinks pointing outward) or that isn't a real .ts file.
 // First arg is the consumer repo root (same as findCodemodScriptsRoot) —
 // not the scripts root — so out-of-tree callers keep compiling against the
-// public upgrade-cli subpath without silently resolving to null (fw#2341).
+// public upgrade-cli subpath without silently resolving to null.
 function resolveCodemodScriptAt(codemodScriptsRoot, codemodField) {
     if (!codemodField)
         return null;
@@ -417,7 +418,7 @@ function parseStoredMarker(raw) {
         resolvedManual: dedupeManualById(resolvedManual),
     };
 }
-// A missing marker is a bootstrap app that never ran `--apply` (fw#2299); an
+// A missing marker is a bootstrap app that never ran `--apply`; an
 // existing but unreadable one must not silently fall back to the installed
 // version, or a bare `--apply` would skip every codemod in between.
 function readMarker(targetDir) {
@@ -512,7 +513,7 @@ function writePartialMarker(out, targetDir, pending, manualEntries, failedVersio
 // failure; codemods that already ran are kept in a partial marker. Writes the
 // marker whenever dryRun is false —
 // even with zero pending entries, so an already-current app still gets a
-// bootstrap marker recording its installed version (fw#2299).
+// bootstrap marker recording its installed version.
 // kumiko-lint-ignore complexity-budget sequential codemod runner with zero-pending bootstrap marker
 async function applyCodemods(out, pending, repoRoot, targetDir, dryRun, 
 // Installed version for the zero-pending bootstrap marker — never a
@@ -751,8 +752,8 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     const installedVersion = readCurrentVersion(cwd);
     // Filter baseline: explicit --from wins, otherwise the marker recorded
     // under targetDir (what was last actually applied there), falling back to
-    // the installed version only when no marker exists yet (bootstrap,
-    // fw#2299). Baselining on installedVersion here would silently treat every
+    // the installed version only when no marker exists yet (bootstrap).
+    // Baselining on installedVersion here would silently treat every
     // changelog entry up to the installed version as already handled, even
     // when the marker says otherwise — a bare `--apply` would then always
     // report "Nothing new" and bootstrap the marker onto the installed

package/dist/utils/compare.js

@@ -1,7 +1,7 @@
 // Locale-independent string ordering for sorts that feed byte-exact serialized
 // artifacts (manifest JSON, snapshot.json, generated migration SQL). Unlike
 // String.localeCompare — whose order depends on the runner's ICU locale and so
-// can drift between a macOS dev box and Linux CI (#330) — this compares by
+// can drift between a macOS dev box and Linux CI — this compares by
 // UTF-16 code unit, which is stable across machines and, for the BMP identifier
 // strings we sort here (table / column / feature / qualified names), equals
 // codepoint order.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.385.0",
+  "version": "0.387.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
-  "license": "BUSL-1.1",
+  "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.385.0",
+    "@cosmicdrift/kumiko-types": "0.387.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.385.0",
+    "@cosmicdrift/kumiko-testing": "0.387.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },