@cosmicdrift/kumiko-framework 0.371.1 → 0.372.0

package/AGENTS.md

@@ -57,7 +57,10 @@ verbs off with `verbs: { delete: false }` and register them yourself when
 they need different access or logic. Custom logic goes into
 `r.writeHandler({ name, schema, handler, access })` and
 `r.queryHandler({ name, schema, handler, access })`; inside, use the entity
-executor from `createEntityExecutor(name, entity)`.
+executor from `createEntityExecutor(name, entity)`. Its `detail` and `list`
+return rows typed from the entity (`EntityRow<typeof entity>`), so
+`row.title` needs no cast; money and located-timestamp fields come back as
+objects, and `create` / `update` payloads stay untyped.
 
 **Screen.** A declarative page: `r.screen({ id, type, ... })`. Types include
 `entityList`, `entityEdit`, `projectionList`, `projectionDetail`,

package/agents/examples/custom-handlers.md

@@ -326,9 +326,6 @@ import {
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 
-// detail() returns an untyped row; parse the two fields the increment needs once.
-const counterVersionRowSchema = z.object({ count: z.number(), version: z.number() });
-
 export const counterEntity = createEntity({
   table: "read_sample_counters",
   fields: {
@@ -365,8 +362,9 @@ export const counterFeature = defineFeature("counters", (r) => {
         return failNotFound("counter", event.payload.id);
       }
 
-      const { count, version } = counterVersionRowSchema.parse(current);
-      const newCount = count + event.payload.amount;
+      // detail() returns the entity's own row type; count is nullable because the field is not required.
+      const { count, version } = current;
+      const newCount = (count ?? 0) + event.payload.amount;
       // Read-modify-write on counter: use the version we just read so two
       // concurrent increments don't clobber each other's changes.
       return counterExecutor.update(

package/agents/examples/embedded-entity-form.md

@@ -427,7 +427,7 @@ export const prospectsFeature = defineFeature("prospects", (r) => {
       const flipped = await suggestionExecutor.update(
         {
           id: event.payload.suggestionId,
-          version: suggestion["version"] as number,
+          version: suggestion["version"],
           changes: { status: "accepted" },
         },
         event.user,

package/agents/examples/pdf-audit-export.md

@@ -14,7 +14,7 @@ A write handler exports tenant data as a PDF and keeps it as a FileRef.
 
 - `renderTablePdf` (`@cosmicdrift/kumiko-bundled-features/renderer-pdf`) draws a table document in pure JavaScript: repeating header, weighted columns, page footer. The handler passes ready-formatted strings.
 - The export is a `beforeTransaction` handler: it reads the rows (reads work in that phase), renders the PDF and calls `uploadFileBytesBeforeTransaction` (`@cosmicdrift/kumiko-framework/files`), which validates the bytes and writes them to the tenant-prefixed storage key. The upload runs before the transaction because storage I/O inside it would hold a pool connection for as long as the upload takes.
-- The handler itself calls `createFileRefFromUploadedBytes(ctx, event.prepared)` and creates the `file_refs` row and the `fileRef.created` event in the transaction. If the transaction does not commit, the phase's `release` deletes the uploaded bytes again (only when no row exists for the storage key). A crash between upload and commit leaves the bytes in storage; nothing sweeps them.
+- The handler itself calls `createFileRefFromUploadedBytes(ctx, event.prepared)` and creates the `file_refs` row and the `fileRef.created` event in the transaction. If the transaction does not commit, the phase's `release` deletes the uploaded bytes again (only when no row exists for the storage key). A crash between upload and commit leaves the bytes in storage; the hourly `files:job:sweep-orphaned-uploads` job deletes them once they are older than the grace period (24 hours by default, `uploadSweepGraceHours`).
 - The result is a normal FileRef: `GET /api/files/:id` serves it with `Content-Type: application/pdf`, other tenants get 404.
 
 ## Source

package/agents/examples/user-data-rights.md

@@ -83,6 +83,28 @@ Step-by-step proof:
 2. Deletion + expired grace → `runForgetCleanup` removes all notes
 3. Strategy `anonymize` → `authorId=null`, title/body remain
 
+## Retention with files
+
+`runRetentionCleanup` is exported for app tests. A `hardDelete` entity with a file field loses
+its bytes (and derivatives), its `file_refs` row and then the row itself; a storage error keeps
+the row and reports `file_delete_failed` in `skipped`. `src/retained-docs.ts` holds the entity,
+`src/__tests__/retention-files.integration.test.ts` drives the run with only public imports:
+
+```ts illustration
+import { runRetentionCleanup } from "@cosmicdrift/kumiko-bundled-features/data-retention";
+import { createFileContext } from "@cosmicdrift/kumiko-framework/files";
+
+const result = await runRetentionCleanup({
+  db: stack.db,
+  registry: stack.registry,
+  tenantId,
+  preloadedTenantPreset: null,
+  now: getTemporal().Now.instant().add({ hours: 31 * 24 }), // keepFor 30d + 1 day
+  files: createFileContext(() => Promise.resolve(provider)), // the stack's storage provider
+});
+// result.hardDeleted === 1, bytes and file_refs row gone
+```
+
 ## Full app vs this recipe
 
 | | This recipe | [user-data-rights-demo](/en/samples/apps-user-data-rights-demo/) |
@@ -300,6 +322,120 @@ describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domai
 });
 ```
 
+### src/__tests__/retention-files.integration.test.ts
+
+```ts
+// runRetentionCleanup is public API: an app test drives the retention run with its own `now`
+// and the stack's storage provider, then checks that the file bytes, the file_refs row and the
+// entity row are gone and the erasure is on the audit trail.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createDataRetentionFeature,
+  runRetentionCleanup,
+  tenantRetentionOverrideEntity,
+} from "@cosmicdrift/kumiko-bundled-features/data-retention";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createFileContext,
+  createFilesFeature,
+  createInMemoryFileProvider,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
+import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import {
+  buildMultipartBody,
+  patchFileInstanceofForBunTest,
+} from "@cosmicdrift/kumiko-testing/helpers";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-testing/stack";
+import { retainedDocEntity, retainedDocsFeature } from "../retained-docs";
+
+const CREATE = "retained-docs:write:retained-doc:create";
+const DETAIL = "retained-docs:query:retained-doc:detail";
+const tenantId = testTenantId(61);
+const admin = createTestUser({ id: 61, tenantId, roles: ["Admin"] });
+const provider = createInMemoryFileProvider();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  patchFileInstanceofForBunTest();
+  stack = await setupTestStack({
+    features: [createFilesFeature(), createDataRetentionFeature(), retainedDocsFeature],
+    files: { storageProvider: provider },
+  });
+  await unsafeCreateEntityTable(stack.db, retainedDocEntity, "retained-doc");
+  await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function upload(): Promise<string> {
+  const fd = new FormData();
+  fd.append("entityType", "retained-doc");
+  fd.append("fieldName", "attachment");
+  fd.append(
+    "file",
+    new File([Buffer.from("%PDF-1.4 minimal")], "doc.pdf", { type: "application/pdf" }),
+  );
+  const { body, contentType } = await buildMultipartBody(fd);
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${await stack.jwt.sign(admin)}`,
+      "Content-Type": contentType,
+    },
+    body,
+  });
+  expect(res.status).toBe(201);
+  return ((await res.json()) as { id: string }).id;
+}
+
+describe("user-data-rights recipe :: retention run removes a hardDelete entity's files", () => {
+  test("after keepFor + 1 day the row, its bytes and its file_refs row are gone; the erasure is audited", async () => {
+    const fileRefId = await upload();
+    const created = await stack.http.writeOk<{ id: string }>(
+      CREATE,
+      { title: "contract", attachment: fileRefId },
+      admin,
+    );
+    const [fileRef] = await selectMany<{ storageKey: string }>(stack.db, fileRefsTable, {
+      id: fileRefId,
+    });
+    const storageKey = String(fileRef?.storageKey);
+    expect(await provider.exists(storageKey)).toBe(true);
+
+    const result = await runRetentionCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      tenantId,
+      preloadedTenantPreset: null,
+      now: getTemporal()
+        .Now.instant()
+        .add({ hours: 31 * 24 }),
+      files: createFileContext(() => Promise.resolve(provider)),
+    });
+
+    expect(result.hardDeleted).toBe(1);
+    expect(result.skipped).toEqual([]);
+    expect(await provider.exists(storageKey)).toBe(false);
+    expect(await selectMany(stack.db, fileRefsTable, { id: fileRefId })).toHaveLength(0);
+    expect(await stack.http.queryOk(DETAIL, { id: created.id }, admin)).toBeNull();
+
+    const forgotten = await selectMany(stack.db, eventsTable, { aggregateId: created.id });
+    expect(forgotten.map((e) => (e as { type: string }).type)).toContain("retained-doc.forgotten");
+  });
+});
+```
+
 ### src/feature.ts
 
 ```ts
@@ -405,3 +541,43 @@ export const notesFeature = defineFeature("notes", (r) => {
   });
 });
 ```
+
+### src/retained-docs.ts
+
+```ts
+// Retention with files: a hardDelete entity whose file field is cleaned up together with the
+// row. runRetentionCleanup removes the bytes (and derivatives) and the file_refs row first,
+// then the row itself; the cron in data-retention does the same with the tenant's FileContext.
+
+import {
+  createEntity,
+  createFileField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDetailHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const retainedDocEntity = createEntity({
+  table: "store_retained_docs",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    attachment: createFileField(),
+  },
+  retention: { keepFor: "30d", strategy: "hardDelete", reference: "createdAt" },
+});
+
+export const retainedDocsFeature = defineFeature("retained-docs", (r) => {
+  r.entity({ name: "retained-doc", ...retainedDocEntity });
+  r.writeHandler(
+    defineEntityCreateHandler("retained-doc", retainedDocEntity, {
+      access: { roles: ["Admin"] },
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler("retained-doc", retainedDocEntity, {
+      access: { roles: ["Admin"] },
+    }),
+  );
+});
+```

package/dist/api/jwt.js

@@ -1,4 +1,5 @@
 import * as jose from "jose";
+import { stripReservedTokenRoles } from "../engine/membership-roles.js";
 import { parseTenantId } from "../engine/types/index.js";
 import { InternalError } from "../errors/index.js";
 function normalizeKeyring(secretOrKeyring) {
@@ -107,7 +108,7 @@ export function createJwtHelper(secretOrKeyring, issuer = "kumiko", ttlSeconds =
             const result = {
                 sub: payload.sub,
                 tenantId,
-                roles,
+                roles: [...stripReservedTokenRoles(roles)],
             };
             if (typeof payload["timezone"] === "string") {
                 result.timezone = payload["timezone"];

package/dist/api/observability-middleware.d.ts

@@ -1,8 +1,7 @@
 import type { Context, Next } from "hono";
-import { type Meter, type SensitiveFilterConfig, type Tracer } from "../observability/index.ts";
+import { type Meter, type Tracer } from "../observability/index.ts";
 export type ObservabilityMiddlewareOptions = {
     readonly tracer: Tracer;
     readonly meter: Meter;
-    readonly sensitiveConfig: SensitiveFilterConfig;
 };
 export declare function observabilityMiddleware(opts: ObservabilityMiddlewareOptions): (c: Context, next: Next) => Promise<void>;

package/dist/api/observability-middleware.js

@@ -1,20 +1,21 @@
-import { emitHttpRequest, observabilityContext, redactQueryString, } from "../observability/index.js";
+import { emitHttpRequest, observabilityContext, } from "../observability/index.js";
 import { getUser } from "./auth-middleware.js";
 import { requestContext } from "./request-context.js";
+import { resolveRouteLabel } from "./route-label.js";
 export function observabilityMiddleware(opts) {
-    const { tracer, meter, sensitiveConfig } = opts;
+    const { tracer, meter } = opts;
     return async (c, next) => {
         const method = c.req.method;
-        const path = c.req.path;
-        const target = redactQueryString(c.req.url.replace(/^https?:\/\/[^/]+/, ""), sensitiveConfig);
+        // The match list is fixed before the first middleware runs, so the label is known up front
+        // and also covers requests that a middleware answers or a handler throws on.
+        const route = resolveRouteLabel(c);
         // Start the root span for this request. kind=server marks it as an
         // incoming server-side span in OTel terms.
-        const span = tracer.startSpan("http.request", {
+        const span = tracer.startSpan(`${method} ${route}`, {
             kind: "server",
             attributes: {
                 "http.method": method,
-                "http.route": path,
-                "http.target": target,
+                "http.route": route,
             },
         });
         const reqCtx = requestContext.get();
@@ -61,7 +62,7 @@ export function observabilityMiddleware(opts) {
             // c.res may be undefined on very early throws (before any route handler);
             // fall back to 500 for the metric so the counter is always incremented.
             const status = c.res?.status ?? 500;
-            emitHttpRequest(meter, { route: path, method, status }, durationSec);
+            emitHttpRequest(meter, { route, method, status }, durationSec);
             span.end();
         }
     };

package/dist/api/pii-leak-guard.js

@@ -1,4 +1,5 @@
 import { PII_CIPHERTEXT_PREFIX } from "../crypto/index.js";
+import { resolveRouteLabel } from "./route-label.js";
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
 // Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
 // older/decrypt-only format version still present in unmigrated rows.
@@ -27,7 +28,7 @@ export function piiCiphertextResponseGuard() {
         // skip: clean response — the common case
         if (!CIPHERTEXT_RE.test(text))
             return;
-        const detail = `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +
+        const detail = `[api] JSON response for ${c.req.method} ${resolveRouteLabel(c)} contains a PII ciphertext ` +
             `("${PII_CIPHERTEXT_PREFIX}…") — a raw DB read leaked to the API surface. ` +
             `Decrypt before returning (decryptStoredPii / executor read path).`;
         if (!isProductionEnv()) {

package/dist/api/route-label.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "hono";
+export declare const UNMATCHED_ROUTE_LABEL = "unmatched";
+export declare function resolveRouteLabel(c: Context): string;

package/dist/api/route-label.js

@@ -0,0 +1,17 @@
+import { matchedRoutes } from "hono/route";
+export const UNMATCHED_ROUTE_LABEL = "unmatched";
+const MIDDLEWARE_METHOD = "ALL";
+// Route pattern (`/api/heartbeat/:token`) instead of the raw path: raw paths carry path-param
+// secrets and make every distinct id its own metric series. Middleware and the notFound fallback
+// register as method "ALL", so only a method-specific match counts as a real route. Reading the
+// match list instead of c.req.routeIndex keeps the label right when a middleware (401, 429)
+// answers before the handler runs.
+export function resolveRouteLabel(c) {
+    const routes = matchedRoutes(c);
+    for (let index = routes.length - 1; index >= 0; index--) {
+        const route = routes[index];
+        if (route && route.method !== MIDDLEWARE_METHOD)
+            return route.path;
+    }
+    return UNMATCHED_ROUTE_LABEL;
+}

package/dist/api/server.d.ts

@@ -4,7 +4,7 @@ import type { PgListenClient } from "../db/connection.ts";
 import { type AppContext, type Registry, type RunIn, type WriteResult } from "../engine/types/index.ts";
 import type { ErrorDocsConfig } from "../errors/docs-url.ts";
 import type { Lifecycle } from "../lifecycle/index.ts";
-import { type ObservabilityOptions, type ObservabilityProvider } from "../observability/index.ts";
+import { type ObservabilityProvider } from "../observability/index.ts";
 import type { DispatcherOptions } from "../pipeline/dispatcher.ts";
 import { type Dispatcher } from "../pipeline/dispatcher.ts";
 import type { EventDedup } from "../pipeline/event-dedup.ts";
@@ -46,7 +46,6 @@ export type ServerOptions = {
         pgClient?: PgListenClient;
     };
     observability?: ObservabilityProvider;
-    observabilityOptions?: ObservabilityOptions;
     rateLimit?: {
         readonly global?: Omit<GlobalIpRateLimitOptions, "resolver">;
         readonly auth?: Omit<AuthEndpointRateLimitOptions, "resolver"> & {

package/dist/api/server.js

@@ -10,13 +10,13 @@ import { resolveDisabledFeatureNames, stripDisabledFeaturesFromAppSchema, } from
 import { createAnonymousUser, createSystemUser, isAnonymousSessionUser, } from "../engine/system-user.js";
 import { isFileField, } from "../engine/types/index.js";
 import { assertSeedModeNotInProduction } from "../event-store/seed-clock.js";
-import { createFileContext } from "../files/file-handle.js";
+import { createTenantFileContext } from "../files/file-handle.js";
 import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
 import { makeFileProviderResolver } from "../files/provider-resolver.js";
 import { createRecordReadCheck } from "../files/record-read-check.js";
 import { createRecordWriteCheck } from "../files/record-write-check.js";
 import { createFallbackLogger } from "../logging/index.js";
-import { createNoopProvider, DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, registerStandardMetrics, wrapRedisClient, } from "../observability/index.js";
+import { createNoopProvider, registerStandardMetrics, wrapRedisClient, } from "../observability/index.js";
 import { resolveTenantLifecyclePlugin } from "../pipeline/active-membership.js";
 import { createDispatcher } from "../pipeline/dispatcher.js";
 import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
@@ -389,7 +389,7 @@ export function buildServer(options) {
             // cross-feature ctx.appendEvent calls at emit-site.
             const mspOwner = msp.name.split(":")[0];
             const mspFiles = fileProviderResolver
-                ? createFileContext(() => fileProviderResolver(event.tenantId), event.tenantId)
+                ? createTenantFileContext(fileProviderResolver, event.tenantId)
                 : undefined;
             const applyCtx = createMultiStreamApplyContext({
                 registry: options.registry,
@@ -467,7 +467,6 @@ export function buildServer(options) {
     // (tenant-by-host), entry:"user" needs c.get("user") populated.
     const extraRoutePublicMatchers = compileExtraRoutePublicMatchers(options.extraRoutes);
     const isExtraRoutePublicPath = (c) => extraRoutePublicMatchers.some((m) => m.method === c.req.method && m.pattern.test(c.req.path));
-    const sensitiveConfig = mergeSensitiveConfig(options.observabilityOptions?.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG);
     registerHealthRoutes(app, {
         lifecycle: options.lifecycle,
         readiness: {
@@ -519,7 +518,6 @@ export function buildServer(options) {
     app.use("/api/*", observabilityMiddleware({
         tracer: observability.tracer,
         meter: observability.meter,
-        sensitiveConfig,
     }));
     // Tripwire: a kumiko-pii: ciphertext in a JSON response is always a bug
     // (raw read leaked past a decrypt) — dev fails loud, prod redacts (#820).

package/dist/config/index.d.ts

@@ -1,3 +1,4 @@
+import type { ValidateBootOptions } from "../engine/boot-validator.ts";
 import type { FeatureDefinition } from "../engine/types/index.ts";
 export type AppInfraPorts = {
     readonly postgres?: number;
@@ -19,6 +20,8 @@ export type AppClientConfig = {
     /** Client bundle entry files, relative to the app root (e.g. "src/client.tsx"). */
     readonly entries: readonly string[];
 };
+/** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
+export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "warnOnUniqueAccessRoles">;
 export type AppConfig = {
     /** Features mounted in every environment: dev, tests, prod. */
     readonly features: readonly FeatureDefinition[];
@@ -26,6 +29,8 @@ export type AppConfig = {
     readonly prodFeatures?: readonly FeatureDefinition[];
     readonly client: AppClientConfig;
     readonly ports: AppPorts;
+    /** Passed to validateBoot by `kumiko check` and, via the app's bin files, by the runners. */
+    readonly validateBootOptions?: AppValidateBootOptions;
 };
 export declare const APP_CONFIG_FILE = "kumiko.config.ts";
 declare const INFRA_PORT_NAMES: readonly ["postgres", "redis", "meilisearch", "s3"];

package/dist/db/event-store-executor.d.ts

@@ -5,6 +5,7 @@ import type { EntityCache } from "../pipeline/entity-cache.ts";
 import type { SearchAdapter } from "../search/types.ts";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher.ts";
 import { type Table } from "./event-store-executor-context.ts";
+import type { EntityRow } from "./table-builder.ts";
 export type { EventStoreExecutor, LockGuardOption, WritePurpose, } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 export { WritePurposes } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 export type { EntityLifecycleVerb } from "./event-store-executor-context.ts";
@@ -18,4 +19,4 @@ export type EventStoreExecutorOptions = {
     /** Override the boot-injected subject KMS for pii-annotated fields. */
     kms?: LocalKeyKmsAdapter;
 };
-export declare function createEventStoreExecutor(table: Table, entity: EntityDefinition, options: EventStoreExecutorOptions): EventStoreExecutor;
+export declare function createEventStoreExecutor<E extends EntityDefinition>(table: Table, entity: E, options: EventStoreExecutorOptions): EventStoreExecutor<EntityRow<E>>;

package/dist/db/index.d.ts

@@ -18,7 +18,7 @@ export { buildEntityTableMeta, defineUnmanagedTable, deriveEntityTableMeta, } fr
 export type { EntityLifecycleVerb, EventStoreExecutor, EventStoreExecutorOptions, LockGuardOption, WritePurpose, } from "./event-store-executor.ts";
 export { createEventStoreExecutor, entityEventName, WritePurposes, } from "./event-store-executor.ts";
 export { enumerateFeatureTableSources, type FeatureTableSource, } from "./feature-table-sources.ts";
-export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.ts";
+export { flattenLocatedTimestamp, type LocatedTimestampRead, rehydrateLocatedTimestamp, } from "./located-timestamp.ts";
 export { assertUniqueTableNames, assertValidMigrationName, diffSnapshots, type GenerateMigrationInput, type GenerateMigrationOutput, generateMigration, loadSnapshotJson, renderMigrationSql, type SchemaDiff, type Snapshot, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.ts";
 export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.ts";
 export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.ts";
@@ -34,6 +34,6 @@ export { renderTableDdl, renderTablesDdl } from "./render-ddl.ts";
 export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, type ReplayMismatch, replayMigrationsDir, } from "./replay-migration-sql.ts";
 export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.ts";
 export { tableExists } from "./schema-inspection.ts";
-export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.ts";
+export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityRow, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.ts";
 export type { CreateTenantDbOptions, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
 export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";

package/dist/db/index.js

@@ -12,7 +12,7 @@ export { entityTableFromRegistry } from "./entity-table-from-registry.js";
 export { buildEntityTableMeta, defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.js";
 export { createEventStoreExecutor, entityEventName, WritePurposes, } from "./event-store-executor.js";
 export { enumerateFeatureTableSources, } from "./feature-table-sources.js";
-export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
+export { flattenLocatedTimestamp, rehydrateLocatedTimestamp, } from "./located-timestamp.js";
 export { assertUniqueTableNames, assertValidMigrationName, diffSnapshots, generateMigration, loadSnapshotJson, renderMigrationSql, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
 export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
 export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";

package/dist/db/located-timestamp.d.ts

@@ -10,6 +10,13 @@ import type { EntityDefinition } from "../engine/types/index.ts";
  * Pure — mutiert nicht.
  */
 export declare function flattenLocatedTimestamp(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
+/** Shape of a single rehydrated locatedTimestamp field. `at` is the wall clock in `tz`
+ *  (no offset), `utc` the ISO instant string; both are strings, not Temporal values. */
+export type LocatedTimestampRead = {
+    readonly at: string;
+    readonly tz: string;
+    readonly utc: string;
+};
 /**
  * DB → API: zwei flache Spalten zu combined { at, tz, utc } rehydraten.
  *

package/dist/db/query.d.ts

@@ -68,7 +68,7 @@ export declare function selectInnerJoin<TLeft = Record<string, unknown>, TRight
 export declare function insertMany<TRow = any>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
 export declare function insertOne<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
 export declare function updateMany<TRow = any>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
-export declare function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<void>;
+export declare function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<number>;
 export declare function resolveConflictColumns(table: TableLike, info: TableInfo, conflictKeys: readonly string[] | undefined): readonly string[];
 export type UpsertOnConflictOptions = {
     readonly conflictKeys: readonly string[];

package/dist/db/query.js

@@ -5,7 +5,7 @@
 //   fetchOne<T>(db, table, where) → T | undefined
 //   insertOne<T>(db, table, values) → T | undefined
 //   updateMany<T>(db, table, set, where) → readonly T[]
-//   deleteMany(db, table, where) → void
+//   deleteMany(db, table, where) → number of deleted rows
 //   countWhere(db, table, where?) → number
 //   upsertByPk / upsertOnConflict / incrementCounter
 //   deleteManyBatched(db, table, where, { limit }) → { deleted, batches }
@@ -1108,10 +1108,16 @@ export async function deleteMany(db, table, where) {
     let sqlText = `DELETE FROM ${quoteIdent(info.name)}`;
     if (w.sqlText)
         sqlText += ` WHERE ${w.sqlText}`;
-    await unsafeLoggingClosedConnection(db, sqlText, w.values, {
+    const result = await unsafeLoggingClosedConnection(db, sqlText, w.values, {
         operation: "deleteMany",
         table: info.name,
     });
+    // postgres-js reports the affected-row count of a DELETE on the result, no RETURNING needed.
+    const count = propertyOf(result, "count");
+    if (typeof count !== "number") {
+        throw new Error(`deleteMany(${info.name}): the driver result carries no affected-row count`);
+    }
+    return count;
 }
 function insertEntries(info, values) {
     return Object.entries(values)

package/dist/db/table-builder.d.ts

@@ -3,6 +3,8 @@ import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type { EntityDefinition, EntityRelations, FieldDefinition, FieldsMap } from "../engine/types/index.ts";
 import type { Table } from "./event-store-executor-context.ts";
+import type { LocatedTimestampRead } from "./located-timestamp.ts";
+import type { MoneyRead } from "./money.ts";
 export { toSnakeCase } from "../utils/case.ts";
 import { type ColumnBuilder, type ColumnHandle, type SchemaTable, type TableColumns } from "./dialect.ts";
 export declare const SOFT_DELETE_LIVE_ROW_PREDICATE = "\"is_deleted\" = false";
@@ -10,25 +12,23 @@ export declare function physicalColumnName(table: Table, field: string): string;
 export type AnyPgColumn = ColumnHandle;
 export declare const READ_MODEL_PREFIX = "read_";
 export declare function toTableName(entityName: string): string;
-type Col<_T> = ColumnHandle & {
+type Col<T> = ColumnHandle & {
     readonly __notNull: true;
+    readonly __value?: T;
 };
-type NullCol<_T> = ColumnHandle & {
+type NullCol<T> = ColumnHandle & {
     readonly __notNull: false;
+    readonly __value?: T;
 };
-type ColumnsForField<K extends string, F extends FieldDefinition> = F extends {
+type ColumnsForField<K extends string, F extends FieldDefinition> = ValueColumnsForField<K, F> & BlindIndexColumnForField<K, F>;
+type BlindIndexColumnForField<K extends string, F extends FieldDefinition> = F extends {
     type: "text";
     lookupable: true;
-} ? (F extends {
-    required: true;
 } ? {
-    readonly [P in K]: Col<string>;
-} : {
-    readonly [P in K]: NullCol<string>;
-}) & {
     readonly [P in `${K}Bidx`]: NullCol<string>;
-} : F extends {
-    type: "text" | "select" | "tz";
+} : unknown;
+type ValueColumnsForField<K extends string, F extends FieldDefinition> = F extends {
+    type: "text" | "longText" | "select" | "tz";
 } ? F extends {
     required: true;
 } ? {
@@ -160,6 +160,40 @@ type SoftDeleteColumnsType = {
     readonly deletedAt: NullCol<Temporal.Instant>;
     readonly deletedById: NullCol<string>;
 };
+type ColumnValue<C> = C extends {
+    readonly __notNull: true;
+    readonly __value?: infer T;
+} ? T : C extends {
+    readonly __notNull: false;
+    readonly __value?: infer T;
+} ? T | null : unknown;
+type RowOfColumns<C> = {
+    readonly [K in keyof C]: ColumnValue<C[K]>;
+};
+type CompoundRowField<K extends string, V, F> = F extends {
+    required: true;
+} ? {
+    readonly [P in K]: V;
+} : {
+    readonly [P in K]?: V;
+};
+type RowForField<K extends string, F extends FieldDefinition> = F extends {
+    type: "money";
+} ? CompoundRowField<K, MoneyRead, F> : F extends {
+    type: "locatedTimestamp";
+} ? CompoundRowField<K, LocatedTimestampRead, F> : [ValueColumnsForField<K, F>] extends [never] ? {
+    readonly [P in K]: unknown;
+} : RowOfColumns<ValueColumnsForField<K, F>>;
+type RowForFields<F extends FieldsMap> = UnionToIntersection<{
+    [K in keyof F & string]: RowForField<K, F[K]>;
+}[keyof F & string]>;
+type SoftDeleteRow<E extends EntityDefinition> = E["softDelete"] extends true ? RowOfColumns<SoftDeleteColumnsType> : [E["softDelete"]] extends [false | undefined] ? unknown : Partial<RowOfColumns<SoftDeleteColumnsType>>;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** The row `executor.list()` / `executor.detail()` return for entity `E`. A wide
+ *  `EntityDefinition` (fields without literal keys) yields `Record<string, unknown>`. */
+export type EntityRow<E extends EntityDefinition = EntityDefinition> = string extends keyof E["fields"] ? Record<string, unknown> : Flatten<RowOfColumns<BaseColumnsType<E>> & SoftDeleteRow<E> & RowForFields<E["fields"]>>;
 export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 export type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 type EntityTableTenancy<E extends EntityDefinition> = [NonNullable<E["tenancy"]>] extends [never] ? "tenant" : [NonNullable<E["tenancy"]>] extends ["global"] ? "global" : "tenant";

package/dist/db/tenant-db.js

@@ -504,7 +504,9 @@ function buildTenantDb(options) {
                     return Promise.reject(new Error("db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition."));
                 }
                 report("global-write", globalWriteReason());
-                return withDbSpan("delete", table, async () => bunDeleteMany(db, table, where));
+                return withDbSpan("delete", table, async () => {
+                    await bunDeleteMany(db, table, where);
+                });
             },
             // @cast-boundary phantom-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };