@cosmicdrift/kumiko-framework 0.361.0 → 0.363.0

package/dist/secrets/stored-envelope.js

@@ -2,6 +2,7 @@
 // jsonb columns (secrets feature) or JSON-stringified TEXT columns
 // (EnvelopeCipher for config values / entity fields). One wire shape for
 // every envelope-encrypted store in the framework.
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 export function encodeStoredEnvelope(envelope) {
     return {
         ciphertext: envelope.ciphertext.toString("base64"),
@@ -21,12 +22,11 @@ export function decodeStoredEnvelope(stored) {
     };
 }
 export function isStoredEnvelope(value) {
-    if (!value || typeof value !== "object")
+    if (!isPlainObject(value))
         return false;
-    const v = value; // @cast-boundary parse-boundary after typeof check
-    return (typeof v["ciphertext"] === "string" &&
-        typeof v["iv"] === "string" &&
-        typeof v["authTag"] === "string" &&
-        typeof v["encryptedDek"] === "string" &&
-        typeof v["kekVersion"] === "number");
+    return (typeof value["ciphertext"] === "string" &&
+        typeof value["iv"] === "string" &&
+        typeof value["authTag"] === "string" &&
+        typeof value["encryptedDek"] === "string" &&
+        typeof value["kekVersion"] === "number");
 }

package/dist/stack/push-entity-projection-tables.js

@@ -1,5 +1,5 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { columnNamesOf, tableExists } from "../db/schema-inspection.js";
+import { schemaTableName } from "../db/table-introspection.js";
 import { addMissingColumns, addMissingIndexes, tableToMeta, unsafePushTables, } from "./table-helpers.js";
 // biome-ignore lint/suspicious/noConsole: stack-internal status logging
 const logInfo = (msg) => console.log(msg);
@@ -29,8 +29,7 @@ export async function pushEntityProjectionTables(stack, registry) {
         if (seen.has(proj.table))
             continue;
         seen.add(proj.table);
-        const tableRec = proj.table;
-        const physical = tableRec[KUMIKO_NAME_SYMBOL];
+        const physical = schemaTableName(proj.table) ?? tableToMeta(proj.table).tableName;
         if (!(await tableExists(stack.db, `public.${physical}`))) {
             missing[projName] = proj.table;
             continue;

package/dist/stack/table-helpers.js

@@ -1,20 +1,19 @@
-import { KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { pgTypeToSqlType } from "../db/dialect.js";
 import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement, } from "../db/queries/ddl.js";
 import { truncateTablesRestartIdentity } from "../db/queries/test-stack.js";
 import { renderTableDdl } from "../db/render-ddl.js";
 import { tableExists } from "../db/schema-inspection.js";
 import { buildEntityTable, toTableName } from "../db/table-builder.js";
+import { asEntityTableMeta, schemaTableName } from "../db/table-introspection.js";
 function tableNameOf(table) {
     if (typeof table !== "object" || table === null) {
         throw new Error("table-helpers: table is not a SchemaTable object");
     }
-    const rec = table;
-    if (typeof rec[KUMIKO_NAME_SYMBOL] === "string")
-        return rec[KUMIKO_NAME_SYMBOL];
-    if (typeof rec.tableName === "string") {
-        return rec.tableName;
-    }
+    const symbolName = schemaTableName(table);
+    if (symbolName !== undefined)
+        return symbolName;
+    if ("tableName" in table && typeof table.tableName === "string")
+        return table.tableName;
     throw new Error("table-helpers: table has no name");
 }
 /**
@@ -36,26 +35,11 @@ export async function unsafeEnsureEntityTable(db, entity, entityName) {
 // Tables produced by the native dialect already carry EntityTableMeta-shape
 // (source/columns/indexes). renderTableDdl converts that to CREATE TABLE +
 // CREATE INDEX statements executed via db/queries/test-stack.
-function isMetaShape(v) {
-    return (typeof v === "object" &&
-        v !== null &&
-        typeof v.tableName === "string" &&
-        Array.isArray(v.columns) &&
-        Array.isArray(v.indexes) &&
-        (v.source === "managed" || v.source === "unmanaged"));
-}
 export function tableToMeta(table) {
-    // table() spreads column handles as enumerable props, so a field named
-    // `columns`/`tableName`/`source`/… shadows the matching meta key — read the
-    // canonical meta from the unshadowable symbol when present.
-    if (table !== null && typeof table === "object") {
-        const fromSymbol = table[KUMIKO_META_SYMBOL];
-        if (isMetaShape(fromSymbol))
-            return fromSymbol;
-    }
-    if (isMetaShape(table))
-        return table;
-    throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
+    const meta = asEntityTableMeta(table);
+    if (!meta)
+        throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
+    return meta;
 }
 /** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
 export async function addMissingColumns(db, tableName, columns) {

package/dist/stack/test-stack.js

@@ -1,3 +1,4 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { buildServer } from "../api/server.js";
 import { createSseBroker } from "../api/sse-broker.js";
 import { validateBoot, validateNavBootSubset } from "../engine/boot-validator/index.js";
@@ -269,11 +270,7 @@ export async function setupTestStack(options) {
         // always-real `testRedis.redis`, independent of whatever extraContext
         // did to `appContext.redis` — an explicit `context.rateLimit` from
         // extraContext still wins (same precedence buildServer documents).
-        // @cast-boundary extraContext is declared Record<string, unknown> (late,
-        // dynamic extension point) — appContext's inferred type doesn't carry a
-        // `rateLimit` key, so reading it back needs the same relaxed boundary
-        // extraContext itself is typed with.
-        const explicitRateLimit = appContext.rateLimit;
+        const explicitRateLimit = propertyOf(appContext, "rateLimit");
         const needsOwnRateLimitResolver = explicitRateLimit === undefined &&
             (appContext.redis === undefined || options.rateLimitNowMs !== undefined);
         const rateLimitFallback = needsOwnRateLimitResolver

package/dist/testing/multipart-helper.d.ts

@@ -1,9 +1,3 @@
-/**
- * Serializes a FormData instance to multipart/form-data bytes.
- *
- * Returns the encoded body and the Content-Type header value (including the
- * generated boundary). Pass both directly to app.request or fetch.
- */
 export declare function buildMultipartBody(fd: FormData): Promise<{
     body: BodyInit;
     contentType: string;

package/dist/testing/multipart-helper.js

@@ -19,6 +19,7 @@
  * Returns the encoded body and the Content-Type header value (including the
  * generated boundary). Pass both directly to app.request or fetch.
  */
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 export async function buildMultipartBody(fd) {
     const boundary = `KumikoBnd${Date.now()}${Math.random().toString(36).slice(2, 8)}`;
     const enc = new TextEncoder();
@@ -64,12 +65,11 @@ export function patchFileInstanceofForBunTest() {
         return;
     Object.defineProperty(File, Symbol.hasInstance, {
         value(instance) {
-            if (typeof instance !== "object" || instance === null)
+            if (!isPlainObject(instance))
                 return false;
-            const f = instance;
-            return (typeof f["name"] === "string" &&
-                typeof f["size"] === "number" &&
-                typeof f["arrayBuffer"] === "function");
+            return (typeof instance["name"] === "string" &&
+                typeof instance["size"] === "number" &&
+                typeof instance["arrayBuffer"] === "function");
         },
         configurable: true,
     });

package/dist/testing/without-ambient-temporal.js

@@ -3,15 +3,15 @@
  * Used by ambient-independence regression tests (kumiko-framework#1525/#1550).
  */
 export async function withoutAmbientTemporal(fn) {
-    const savedGlobal = globalThis.Temporal;
-    delete globalThis.Temporal;
+    const savedGlobal = Reflect.get(globalThis, "Temporal");
+    Reflect.deleteProperty(globalThis, "Temporal");
     try {
         return await fn();
     }
     finally {
         if (savedGlobal === undefined)
-            delete globalThis.Temporal;
+            Reflect.deleteProperty(globalThis, "Temporal");
         else
-            globalThis.Temporal = savedGlobal;
+            Reflect.set(globalThis, "Temporal", savedGlobal);
     }
 }

package/dist/ui-types/card-column-roles.d.ts

@@ -5,10 +5,15 @@ export type CardRoleColumn = {
     readonly type?: string;
     readonly renderer?: unknown;
     readonly hideOnNarrow?: boolean;
+    readonly fileDisplay?: {
+        readonly kind: string;
+    };
 };
 export type CardColumnRoles<C extends CardRoleColumn> = {
+    readonly image: C | undefined;
     readonly title: C | undefined;
     readonly status: C | undefined;
     readonly meta: readonly C[];
 };
+export declare function cardFileDisplayKind(type: string | undefined, renderer: unknown): "image" | "file" | undefined;
 export declare function cardColumnRoles<C extends CardRoleColumn>(columns: readonly C[]): CardColumnRoles<C>;

package/dist/ui-types/card-column-roles.js

@@ -1,9 +1,27 @@
 export const CARD_META_MAX = 3;
+// An explicit `{ format: "image" | "file" }` renderer wins over the field type, the
+// same precedence as the list view model's file display.
+export function cardFileDisplayKind(type, renderer) {
+    if (typeof renderer === "object" && renderer !== null && "format" in renderer) {
+        if (renderer.format === "image")
+            return "image";
+        if (renderer.format === "file")
+            return "file";
+    }
+    if (type === "image" || type === "images")
+        return "image";
+    if (type === "file" || type === "files")
+        return "file";
+    return undefined;
+}
 // One rule for the narrow-layout list card, shared by the renderer and the
 // boot validator so the validator counts exactly what the card would draw.
+// The first image column is the card's leading preview, neither title nor meta.
 export function cardColumnRoles(columns) {
-    const title = columns.find((col) => col.highlighted === true) ?? columns[0];
-    const status = columns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
-    const meta = columns.filter((col) => col !== title && col !== status && col.hideOnNarrow !== true);
-    return { title, status, meta };
+    const image = columns.find((col) => col.fileDisplay?.kind === "image");
+    const textColumns = columns.filter((col) => col !== image);
+    const title = textColumns.find((col) => col.highlighted === true) ?? textColumns[0];
+    const status = textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
+    const meta = textColumns.filter((col) => col !== title && col !== status && col.hideOnNarrow !== true);
+    return { image, title, status, meta };
 }

package/dist/ui-types/index.d.ts

@@ -17,7 +17,7 @@ export type { WorkspaceDefinition } from "../engine/types/workspace.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app-schema.js";
 export type { CardColumnRoles, CardRoleColumn } from "./card-column-roles.js";
-export { CARD_META_MAX, cardColumnRoles } from "./card-column-roles.js";
+export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { type Formality, formalLocaleTag } from "./formality.js";
 export type { ListRowMetaColumnType, ListRowMetaReference, ReferenceLookupSource, SystemReferenceLabel, } from "./list-row-meta.js";
 export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";

package/dist/ui-types/index.js

@@ -26,7 +26,7 @@ export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findU
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
-export { CARD_META_MAX, cardColumnRoles } from "./card-column-roles.js";
+export { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind } from "./card-column-roles.js";
 export { formalLocaleTag } from "./formality.js";
 export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";
 export { resolveTranslationValue, translationValueOtherText, } from "./plural.js";

package/dist/utils/is-plain-object.d.ts

@@ -1,2 +1 @@
-/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";

package/dist/utils/is-plain-object.js

@@ -1,4 +1 @@
-/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
-export function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.361.0",
+  "version": "0.363.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.361.0",
-    "@cosmicdrift/kumiko-types": "0.361.0",
+    "@cosmicdrift/kumiko-http": "0.363.0",
+    "@cosmicdrift/kumiko-types": "0.363.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.361.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.363.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,92 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Fewer unchecked casts in bundled features, dev-server, server-runtime, testing and cli",
+    "detail": "Casts are replaced by shared type guards, typed query rows and direct Bun typings. Behavior stays the same, except that a tier-resolver registration without a build() factory now fails with a clear error at boot, the kumiko CLI prints the thrown value of non-Error failures instead of \"undefined\"."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Remove unknown cast-boundary reasons and share propertyOf",
+    "detail": "Framework internals read untyped properties through the shared propertyOf from kumiko-types instead of private copies and casts. The as-casts guard knows four more boundary reasons (phantom-brand, third-party-type-gap, dom-event-target, feature-exports) and normalizes whitespace in cast targets so re-indenting a multi-line cast no longer counts as a regression. A stored inbound-mail cursor that is not a JSON object is now treated like a missing cursor."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "ctx.notify in write handlers delivers after commit",
+    "detail": "Inside a write handler's transaction ctx.notify only records the notification and delivers it once the write has committed, so a rolled-back write sends nothing and leaves no attempt event. Delivery no longer takes a connection from the app pool while the write holds one, which deadlocked at pool max N with N parallel writes. With immediate: true the call stays synchronous and runs its DB work on the outside-transaction pool.",
+    "migration": "NotifyResult is now a union, NotifyDispatched ({ kind: \"dispatched\", deliveries }) or NotifyDeferred ({ kind: \"deferred\" }). In a write handler without immediate: true ctx.notify returns deferred and delivers after commit (a rollback means no notification). Code that reads the result (for example a \"send test message\" handler showing sent/failed) sets immediate: true, which delivers synchronously on the outside-transaction pool and returns dispatched; narrow on kind before reading deliveries. Errors such as a missing idempotency Redis, a tenant broadcast without the tenant feature or an unknown notification type no longer throw in a deferred write handler, they land in the afterCommit log. Notifications from jobs, from seeding and from handlers without a transaction stay synchronous. The boot default wires tenantUserIdsQuery for to: { tenant } when the tenant feature is mounted, so an app-side tenantUserIdsQuery wiring can go. Custom NotifyFactory implementations receive an optional 4th parameter deliveryDb, and DeliveryService.notify an optional 6th."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Shared type guards and fewer unchecked casts in framework internals",
+    "detail": "\"@cosmicdrift/kumiko-types/type-guards\" exports isPlainObject, isOneOf and errorCodeOf. The framework replaces many unchecked as-casts with narrowing, generic query rows and table-introspection helpers. encryptPiiFieldValues is generic over the row and returns PiiEncryptedRow<TRow>, so callers read encrypted fields without casts. Behavior stays the same."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "r.notification declares variables, template and meta; applyBootSeeds seeds them",
+    "detail": "r.notification accepts variables (typed with templateVariable.text, link, money, date and list), template (per locale body, document html) and meta (per locale subject and more). Boot validation requires a kebab-case name, a meta.<locale>.subject for every template locale and valid placeholder names. templateVariablesToZod turns the variables into a Zod schema. applyBootSeeds calls seedNotificationTemplates, which writes the text as system templates of kind mail and fails loudly when notifications declare a template but the template-resolver feature is not mounted."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "r.notification works without trigger and ships localized templates",
+    "detail": "trigger, recipient and data are optional and must be declared together, a notification without trigger is sent explicitly through ctx.notify. localizedTemplate groups body and meta per locale and is mutually exclusive with template and meta. The variable names link, money and date are reserved for template helpers. ctx.notify validates the data against the declared variables and fails the write on a missing required variable. New exports are listMailLocales, hasMailTranslationKey, assertNotificationVariables and NotificationLocalizedTemplate."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "ctx.notify rejects a broadcast to another tenant",
+    "detail": "A notify with to: { tenant } now throws an AccessDeniedError (reason notify_foreign_tenant_broadcast) unless the tenant is the caller's own, before any delivery work. In a write handler it fails synchronously instead of landing in the afterCommit log. Notifications fired from seed hooks during self-signup no longer use the app pool inside the signup transaction, which deadlocked at pool max N with N parallel signups; they deliver after commit. ctx.scheduleAfterCommit is now absent in query bridges and post-commit contexts, where hooks pushed to it never ran; callers that check for it (cache-sync announce, set-tenant-tier onAssigned, form-draft discard, seed hooks) now run inline there instead of being dropped.",
+    "migration": "to: { tenant } must be the tenant of the caller (user.tenantId of the handler or job context), otherwise notify throws; in a write handler the throw is synchronous. Seed-hook notifications in the signup transaction run after commit and return { kind: \"deferred\" } (immediate: true runs synchronously on the outside-transaction pool, which cannot see rows the signup transaction has not committed yet, so a tenant broadcast there finds no new member). No known consumer broadcasts to a foreign tenant."
+  },
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "Client schema carries entity lockedWhen",
+    "detail": "buildAppSchema projects lockedWhen, so an entityEdit screen shows a locked record read-only without a screen-level readOnly."
+  },
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "r.secret options with function values (redact) no longer fail to parse",
+    "detail": "r.secret(...) options that contain arrow or function expressions (for example redact: () => \"••••••••\") were reported as \"options could not be read as a plain object\", which turned the whole feature into a legacy corpus entry. The functions are now kept verbatim as raw references, option keys stay visible and a parse to render round-trip keeps them (multi-line function bodies may be re-indented). Function values in other patterns (entity, nav, metric, job) are still rejected on purpose.",
+    "migration": "Consumers that ship a checked-in few-shot corpus (Enterprise) should regenerate it on the next framework bump; its drift test enforces that."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "Binding of referenced files only for the record creator's own uploads",
+    "detail": "files:write:bind-referenced-files now binds a file only if the record creator uploaded it (or the system generated it), so foreign references cannot expose private uploads."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "files:write:bind-referenced-files binds a record's referenced files",
+    "detail": "System-only handler that binds the files a record references through its declared file fields (legacy uploads with entityId null, records created without a save lifecycle) so record readers can open them. Skips files bound elsewhere, of another tenant or missing. Callable from es-ops seeds via ctx.systemWriteAs; pages with limit and nextAfterId."
+  },
+  {
+    "version": "0.362.0",
+    "type": "breaking",
+    "title": "Optional number fields in entity forms start empty instead of 0",
+    "migration": "An optional number field without default no longer starts at 0 in entityEdit create/edit, and an untouched one is not sent. If a screen relied on the implicit 0, declare default: 0 on the field."
+  },
+  {
+    "version": "0.362.0",
+    "type": "improvement",
+    "title": "unclaimedUploadReaders option for createFilesFeature",
+    "detail": "Roles listed in unclaimedUploadReaders may read (not delete) uploads that have no entityType and entityId, for documents referenced without a file field."
+  },
+  {
+    "version": "0.362.0",
+    "type": "fix",
+    "title": "Query handlers may declare personalData public-intake",
+    "detail": "The personal-data write gate computed the public-intake exemption only for write handlers, so an anonymous query handler that wrote personal data (directly or through a nested write) was always rejected, and the boot validator refused access.personalData on query handlers. Query handlers now follow the same rules as write handlers: access.personalData \"public-intake\" requires the anonymous role and an active rateLimit (not disabled). openToAll.personalData stays write-only, stream handlers still cannot declare personalData.",
+    "migration": "No consumer change; anonymous query handlers that write personal data now declare access.personalData: \"public-intake\" instead of failing at the write gate."
+  },
   {
     "version": "0.361.0",
     "type": "improvement",