@cosmicdrift/kumiko-framework 0.393.0 → 0.394.0

package/dist/pipeline/aggregate-type-removal.d.ts

@@ -0,0 +1,37 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { DbConnection } from "../db/connection.ts";
+import type { Registry } from "../engine/types/feature.ts";
+export declare class AggregateTypeRemovalError extends Error {
+    constructor(message: string);
+}
+export type AggregateTypeStats = {
+    readonly aggregateType: string;
+    readonly events: number;
+    readonly aggregates: number;
+    readonly tenants: number;
+};
+export type WipedProjection = {
+    readonly projection: string;
+    readonly table: EntityTableMeta;
+};
+export type AggregateTypeRemovalPlan = {
+    readonly stats: readonly AggregateTypeStats[];
+    readonly wipedProjections: readonly WipedProjection[];
+};
+export type AggregateTypeRemovalDeleted = {
+    readonly events: number;
+    readonly snapshots: number;
+    readonly archivedStreams: number;
+    readonly upcasterDeadLetters: number;
+    readonly rebuildDeadLetters: number;
+    readonly projectionRows: Readonly<Record<string, number>>;
+};
+export type AggregateTypeRemovalResult = {
+    readonly plan: AggregateTypeRemovalPlan;
+    readonly deleted?: AggregateTypeRemovalDeleted;
+};
+export type RemoveAggregateTypesOptions = {
+    readonly types: readonly string[];
+    readonly apply: boolean;
+};
+export declare function removeAggregateTypes(db: DbConnection, registry: Registry, options: RemoveAggregateTypesOptions): Promise<AggregateTypeRemovalResult>;

package/dist/pipeline/aggregate-type-removal.js

@@ -0,0 +1,146 @@
+import { lockEventConsumersShareMode } from "../db/queries/event-consumer.js";
+import { aggregateWhere, deleteMany, transaction } from "../db/query.js";
+import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
+import { tableExists } from "../db/schema-inspection.js";
+import { asEntityTableMeta, tableNameOf } from "../db/table-introspection.js";
+import { withExecutorManagedWrites } from "../db/tenant-db.js";
+import { archivedStreamsTable } from "../event-store/archive.js";
+import { eventsTable } from "../event-store/events-schema.js";
+import { rebuildDeadLetterTable } from "../event-store/rebuild-dead-letter.js";
+import { snapshotsTable } from "../event-store/snapshot.js";
+import { upcasterDeadLetterTable } from "../event-store/upcaster-dead-letter.js";
+// Whole-type removal for aggregate types that must not survive in the event log, e.g. old events
+// that no longer replay into their projection (a column became NOT NULL) and block
+// `schema apply`. pruneEvents (event-retention.ts) cannot do this: it is age-bound, events-only
+// and refuses while a consumer lags. Here the lag is ignored on purpose, because the removed
+// types leave the log entirely and no consumer has anything left to deliver for them.
+export class AggregateTypeRemovalError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AggregateTypeRemovalError";
+    }
+}
+async function countDistinct(db, field, aggregateType) {
+    const rows = await aggregateWhere(db, eventsTable, { measure: { fn: "countDistinct", field } }, { aggregateType });
+    return rows[0]?.value ?? 0;
+}
+async function countEvents(db, aggregateType) {
+    const rows = await aggregateWhere(db, eventsTable, { measure: { fn: "count" } }, { aggregateType });
+    return rows[0]?.value ?? 0;
+}
+async function statsOf(db, aggregateType) {
+    return {
+        aggregateType,
+        events: await countEvents(db, aggregateType),
+        aggregates: await countDistinct(db, "aggregateId", aggregateType),
+        tenants: await countDistinct(db, "tenantId", aggregateType),
+    };
+}
+// "app-release.created" -> "app-release"; qualified names without a dot carry no aggregate type.
+function aggregateTypeOfEventType(eventType) {
+    const dot = eventType.indexOf(".");
+    return dot === -1 ? undefined : eventType.slice(0, dot);
+}
+// A projection fed only by removed types would be rebuilt to empty, so its rows are deleted. One
+// that also reads other types would keep rows from the removed ones until a rebuild; guessing
+// which rows belong to which type is not possible (row ids are projection-specific), so the
+// whole run refuses instead of leaving ghost rows that the next rebuild aborts on.
+function classifyFeed(involved, removed) {
+    const touched = [...involved].filter((type) => removed.has(type));
+    if (touched.length === 0)
+        return "untouched";
+    return touched.length === involved.size ? "wipe" : "mixed";
+}
+function tableMetaOrThrow(table, owner) {
+    const meta = asEntityTableMeta(table);
+    if (meta === undefined) {
+        throw new AggregateTypeRemovalError(`"${owner}" has a table (${tableNameOf(table)}) without table metadata; cannot remove its rows.`);
+    }
+    return meta;
+}
+function planProjections(registry, removed) {
+    const wiped = [];
+    const refused = [];
+    const consider = (name, involved, table) => {
+        const feed = classifyFeed(involved, removed);
+        if (feed === "mixed")
+            refused.push(`${name} (${[...involved].sort().join(", ")})`);
+        if (feed === "wipe")
+            wiped.push({ projection: name, table: tableMetaOrThrow(table, name) });
+    };
+    for (const [name, def] of registry.getAllProjections()) {
+        const involved = new Set([
+            ...(Array.isArray(def.source) ? def.source : [def.source]),
+            ...(def.extraSources ?? []),
+        ]);
+        consider(name, involved, def.table);
+    }
+    for (const [name, def] of registry.getAllMultiStreamProjections()) {
+        if (def.table === undefined)
+            continue;
+        const involved = new Set();
+        for (const eventType of Object.keys(def.apply)) {
+            // A qualified event name ("feature:event:name") carries no aggregate type; keeping it as its
+            // own entry makes a projection that also reads a removed type "mixed" instead of wiping it.
+            involved.add(aggregateTypeOfEventType(eventType) ?? eventType);
+        }
+        consider(name, involved, def.table);
+    }
+    if (refused.length > 0) {
+        throw new AggregateTypeRemovalError(`Refusing: these projections are fed by removed AND other aggregate types, so their rows cannot be ` +
+            `split by type: ${refused.join("; ")}. Nothing was deleted.`);
+    }
+    return wiped;
+}
+async function assertTypesKnown(registry, stats) {
+    const unknown = stats
+        .filter((s) => s.events === 0 && !registry.getAllEntities().has(s.aggregateType))
+        .map((s) => s.aggregateType);
+    if (unknown.length > 0) {
+        throw new AggregateTypeRemovalError(`Unknown aggregate type(s): ${unknown.join(", ")} (no registered entity and no events). Nothing was deleted.`);
+    }
+}
+async function planRemoval(db, registry, types) {
+    const stats = [];
+    for (const type of types)
+        stats.push(await statsOf(db, type));
+    await assertTypesKnown(registry, stats);
+    return { stats, wipedProjections: planProjections(registry, new Set(types)) };
+}
+async function deleteIfPresent(tx, table, tableName, types) {
+    // Dead-letter and archive tables are created lazily, so a fresh database may not have them.
+    if (!(await tableExists(tx, `public.${tableName}`)))
+        return 0;
+    return deleteMany(tx, table, { aggregateType: [...types] });
+}
+async function applyRemoval(tx, plan, types) {
+    const projectionRows = {};
+    const managed = withExecutorManagedWrites(tx);
+    for (const { projection, table } of plan.wipedProjections) {
+        projectionRows[projection] = await deleteMany(managed, table, {});
+    }
+    return {
+        events: await deleteMany(tx, eventsTable, { aggregateType: [...types] }),
+        snapshots: await deleteIfPresent(tx, snapshotsTable, "kumiko_snapshots", types),
+        archivedStreams: await deleteIfPresent(tx, archivedStreamsTable, "kumiko_archived_streams", types),
+        upcasterDeadLetters: await deleteIfPresent(tx, upcasterDeadLetterTable, "kumiko_upcaster_dead_letters", types),
+        rebuildDeadLetters: await deleteIfPresent(tx, rebuildDeadLetterTable, "kumiko_rebuild_dead_letters", types),
+        projectionRows,
+    };
+}
+export async function removeAggregateTypes(db, registry, options) {
+    if (options.types.length === 0 || options.types.some((type) => type.length === 0)) {
+        throw new AggregateTypeRemovalError("At least one non-empty aggregate type is required.");
+    }
+    return runInSystemRowLevelSecurityScope("aggregate type removal deletes the events and read rows of all tenants", () => transaction(db, async (tx) => {
+        if (options.apply) {
+            // Same lock as pruneEvents: no consumer may bootstrap or advance its cursor between the
+            // plan and the delete.
+            await lockEventConsumersShareMode(tx);
+        }
+        const plan = await planRemoval(tx, registry, options.types);
+        if (!options.apply)
+            return { plan };
+        return { plan, deleted: await applyRemoval(tx, plan, options.types) };
+    }));
+}

package/dist/pipeline/catch-up-job-consumer.d.ts

@@ -0,0 +1,15 @@
+import type { JobDefinition } from "@cosmicdrift/kumiko-types/config";
+import type { JobRunnerRef } from "@cosmicdrift/kumiko-types/handlers";
+import type { DbConnection } from "../db/connection.ts";
+import { type EventUpcasters } from "../event-store/upcaster.ts";
+import type { EventConsumer } from "./event-dispatcher.ts";
+export declare const CATCH_UP_JOB_CONSUMER_PREFIX = "job:";
+type EventJobTrigger = Extract<JobDefinition["trigger"], {
+    readonly on: unknown;
+}>;
+export declare function catchUpEventTypesOf(trigger: EventJobTrigger): ReadonlySet<string>;
+export declare function createCatchUpJobEventConsumer(jobRunner: JobRunnerRef, jobName: string, featureName: string | undefined, eventTypes: ReadonlySet<string>, upcast: {
+    readonly db: DbConnection;
+    readonly upcasters: EventUpcasters;
+}): EventConsumer;
+export {};

package/dist/pipeline/catch-up-job-consumer.js

@@ -0,0 +1,38 @@
+import { upcastStoredEvent } from "../event-store/upcaster.js";
+export const CATCH_UP_JOB_CONSUMER_PREFIX = "job:";
+export function catchUpEventTypesOf(trigger) {
+    const entries = Array.isArray(trigger.on) ? trigger.on : [trigger.on];
+    return new Set(entries.map((entry) => (typeof entry === "string" ? entry : entry.name)));
+}
+// One consumer per catchUp job: its own cursor starts at the beginning of the
+// event store, so events older than the job are replayed too. The enqueue id is
+// deterministic (job QN + event id), see catchUpJobId. Replayed events can be
+// older than the event's current schema, so they are upcast before the job sees them. Events
+// outside the trigger's types return before the upcast: another event's broken upcaster must
+// not stall this job's cursor.
+export function createCatchUpJobEventConsumer(jobRunner, jobName, featureName, eventTypes, upcast) {
+    return {
+        name: `${CATCH_UP_JOB_CONSUMER_PREFIX}${jobName}`,
+        delivery: "shared",
+        startFrom: "beginning",
+        ...(featureName !== undefined && { featureName }),
+        handler: async (storedEvent) => {
+            // skip: not one of this job's trigger events; the runner never matches it anyway
+            if (!eventTypes.has(storedEvent.type))
+                return;
+            const event = await upcastStoredEvent(storedEvent, upcast.upcasters, {
+                db: upcast.db,
+                tenantId: storedEvent.tenantId,
+            });
+            const user = {
+                id: event.metadata.userId,
+                tenantId: event.tenantId,
+                roles: [],
+            };
+            await jobRunner.handleCatchUpEvent?.(jobName, event.type, event.payload, user, {
+                id: event.id,
+                headers: event.metadata.headers ?? {},
+            });
+        },
+    };
+}

package/dist/pipeline/dispatch-write.js

@@ -19,7 +19,7 @@ import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, is
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
 import { perCommandNestedDenied } from "./handler-context-phase-denials.js";
 import { runPreHandlerGates } from "./pre-handler-gates.js";
-import { consumeReservation, hasPreTransactionPhase, } from "./pre-transaction-reservations.js";
+import { consumeReservation, hasPreTransactionPhase, nestedPreTransactionDenial, } from "./pre-transaction-reservations.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
     const { registry, tableCache } = ctx;
@@ -390,14 +390,9 @@ async function runWriteGates(ctx, handler, type, payload, user) {
     if (!gates.isSuccess)
         return failedStep(gates);
     const parsedPayload = reservation ? reservation.parsedPayload : gates.payload;
-    // A handler with a pre-transaction phase cannot run that phase from inside an open transaction;
-    // running it without would skip the reservation or the prepared data, so a nested ctx.dispatch.write of
-    // such a handler is rejected instead.
-    if (needsPreTransactionPhase && !reservation) {
-        return failedStep(writeFailure(new InternalError({
-            message: `handler "${type}" has a pre-transaction phase (reserveBeforeTransaction/beforeTransaction) and cannot run as a nested write unless the top-level command ran it`,
-        })));
-    }
+    const nestedDenial = reservation ? undefined : nestedPreTransactionDenial(handler, type);
+    if (nestedDenial)
+        return failedStep(nestedDenial);
     return { kind: "run", parsedPayload, reservation };
 }
 // Reads via the guard's own db handle — for r.systemScope() handlers

package/dist/pipeline/job-trigger-consumer.d.ts

@@ -0,0 +1,5 @@
+import type { JobRunnerRef } from "@cosmicdrift/kumiko-types/handlers";
+import type { Registry } from "../engine/types/index.ts";
+import type { EventConsumer } from "./event-dispatcher.ts";
+export declare const JOB_TRIGGER_CONSUMER_NAME = "system:consumer:job-trigger";
+export declare function createJobTriggerEventConsumer(jobRunner: JobRunnerRef, registry: Registry): EventConsumer;

package/dist/pipeline/job-trigger-consumer.js

@@ -0,0 +1,48 @@
+// --- Job-Trigger Consumer (async, via event-dispatcher) ---
+//
+// r.job's `trigger.on` historically only fired via the synchronous
+// write-handler dispatch path (dispatch-write.ts's afterCommitHooks calling
+// jobRunner.handleEvent). Events appended any other way — an
+// r.multiStreamProjection's ctx.events.unsafeAppend, or a raw
+// event-store-executor write (e.g. `files`' fileRef.created) — never
+// reached it, so a job could never trigger on an r.defineEvent-registered
+// event.
+//
+// This consumer closes that gap the same way search/SSE do: read every
+// committed event off the shared cursor and re-check job triggers. It is
+// scoped EXACTLY to the gap — the write/query-handler-QN skip below is
+// defense-in-depth: no stored event's `type` is a handler QN today (entity
+// events are "entity.verb"; ctx.events.append enforces defineEvent-only
+// ownership), but if that ever changes, this consumer must not re-fire a
+// trigger the synchronous dispatch-write.ts path already handled.
+//
+// Delivery is at-least-once (cursor semantics) where the synchronous path
+// is effectively once — job handlers reached via an r.defineEvent trigger
+// must be idempotent (same expectation r.multiStreamProjection applies
+// already carry).
+export const JOB_TRIGGER_CONSUMER_NAME = "system:consumer:job-trigger";
+export function createJobTriggerEventConsumer(jobRunner, registry) {
+    return {
+        name: JOB_TRIGGER_CONSUMER_NAME,
+        handler: async (event) => {
+            // skip: write/query-handler QN — already dispatched synchronously by
+            // dispatch-write.ts's afterCommitHooks. Re-firing here would
+            // double-enqueue every existing handler-triggered job.
+            if (registry.getWriteHandler(event.type) || registry.getQueryHandler(event.type))
+                return;
+            // skip: no r.defineEvent registered under this type — nothing this
+            // consumer is responsible for.
+            if (!registry.getEvent(event.type))
+                return;
+            const user = {
+                id: event.metadata.userId,
+                tenantId: event.tenantId,
+                roles: [],
+            };
+            await jobRunner.handleEvent(event.type, event.payload, user, {
+                id: event.id,
+                headers: event.metadata.headers ?? {},
+            });
+        },
+    };
+}

package/dist/pipeline/pre-transaction-reservations.d.ts

@@ -1,6 +1,6 @@
-import type { ReservationHandle, WriteHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
+import type { ReservationHandle, WriteHandlerDef, WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import type { SessionUser } from "../engine/types/index.ts";
-import type { WriteErrorInfo } from "../errors/index.ts";
+import { type WriteErrorInfo } from "../errors/index.ts";
 import type { BatchCommand, DispatchContext } from "./dispatch-shared.ts";
 import type { WriteOrigin } from "./write-origin.ts";
 type ReservationConfirm = ReservationHandle["confirmInTransaction"];
@@ -10,6 +10,7 @@ export type ConsumedReservation = {
     readonly parsedPayload: unknown;
 };
 export declare function hasPreTransactionPhase(handler: WriteHandlerDef): boolean;
+export declare function nestedPreTransactionDenial(handler: WriteHandlerDef, type: string): WriteResult | undefined;
 export declare function runAsCommand<T>(reserved: {
     readonly type: string;
     readonly reservation: ConsumedReservation;

package/dist/pipeline/pre-transaction-reservations.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { InternalError, writeFailure } from "../errors/index.js";
 import { toWriteErrorInfo } from "../errors/write-error-info.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { buildHandlerContext, isMemberResolutionPrincipal } from "./dispatch-shared.js";
@@ -8,6 +9,21 @@ import { effectiveWriteOrigin, rootWriteOrigin } from "./write-origin.js";
 export function hasPreTransactionPhase(handler) {
     return handler.reserveBeforeTransaction !== undefined || handler.beforeTransaction !== undefined;
 }
+// beforeTransactionWhenNested: "skip" lets the handler run nested without the phase and does the work itself.
+// Boot validation rejects the option next to a reservation, so only beforeTransaction is skipped here.
+function runsWithoutPhaseWhenNested(handler) {
+    return (handler.beforeTransactionWhenNested === "skip" && handler.reserveBeforeTransaction === undefined);
+}
+// For a run the top-level command did not prepare. A pre-transaction phase cannot run from inside an
+// open transaction, and running without it would skip the reservation or the prepared data, so a
+// nested ctx.dispatch.write of such a handler is rejected instead.
+export function nestedPreTransactionDenial(handler, type) {
+    if (!hasPreTransactionPhase(handler) || runsWithoutPhaseWhenNested(handler))
+        return undefined;
+    return writeFailure(new InternalError({
+        message: `handler "${type}" has a pre-transaction phase (reserveBeforeTransaction/beforeTransaction) and cannot run as a nested write unless the top-level command ran it`,
+    }));
+}
 // One-shot permission per top-level command: the handler that reserved before the transaction
 // consumes it on entry. A capped handler reached any other way (nested ctx.dispatch.write, writeAs, a
 // second execution of the same type) finds it spent and is rejected instead of running unreserved.

package/dist/pipeline/system-hooks.d.ts

@@ -1,4 +1,3 @@
-import type { JobRunnerRef } from "@cosmicdrift/kumiko-types/handlers";
 import type { EntityId } from "@cosmicdrift/kumiko-types/identifiers";
 import { type SseBroker } from "../api/sse-broker.ts";
 import type { Registry, TenantId } from "../engine/types/index.ts";
@@ -21,8 +20,6 @@ export declare function hasErasedSearchableSubjectField(entityName: string, stat
 export declare function buildSearchDocument(entityName: string, entityId: EntityId, state: Record<string, unknown>, registry: Registry): Promise<SearchDocument | null>;
 export declare const SSE_BROADCAST_CONSUMER_NAME = "system:consumer:sse-broadcast";
 export declare function createSseBroadcastEventConsumer(sseBroker: SseBroker): EventConsumer;
-export declare const JOB_TRIGGER_CONSUMER_NAME = "system:consumer:job-trigger";
-export declare function createJobTriggerEventConsumer(jobRunner: JobRunnerRef, registry: Registry): EventConsumer;
 export declare const ACCESS_INVALIDATION_CONSUMER_NAME = "system:consumer:access-invalidation";
 export declare function createAccessInvalidationEventConsumer(sseBroker: SseBroker, opts?: {
     readonly now?: () => number;

package/dist/pipeline/system-hooks.js

@@ -419,54 +419,6 @@ export function createSseBroadcastEventConsumer(sseBroker) {
         },
     };
 }
-// --- Job-Trigger Consumer (async, via event-dispatcher) ---
-//
-// r.job's `trigger.on` historically only fired via the synchronous
-// write-handler dispatch path (dispatch-write.ts's afterCommitHooks calling
-// jobRunner.handleEvent). Events appended any other way — an
-// r.multiStreamProjection's ctx.events.unsafeAppend, or a raw
-// event-store-executor write (e.g. `files`' fileRef.created) — never
-// reached it, so a job could never trigger on an r.defineEvent-registered
-// event.
-//
-// This consumer closes that gap the same way search/SSE do: read every
-// committed event off the shared cursor and re-check job triggers. It is
-// scoped EXACTLY to the gap — the write/query-handler-QN skip below is
-// defense-in-depth: no stored event's `type` is a handler QN today (entity
-// events are "entity.verb"; ctx.events.append enforces defineEvent-only
-// ownership), but if that ever changes, this consumer must not re-fire a
-// trigger the synchronous dispatch-write.ts path already handled.
-//
-// Delivery is at-least-once (cursor semantics) where the synchronous path
-// is effectively once — job handlers reached via an r.defineEvent trigger
-// must be idempotent (same expectation r.multiStreamProjection applies
-// already carry).
-export const JOB_TRIGGER_CONSUMER_NAME = "system:consumer:job-trigger";
-export function createJobTriggerEventConsumer(jobRunner, registry) {
-    return {
-        name: JOB_TRIGGER_CONSUMER_NAME,
-        handler: async (event) => {
-            // skip: write/query-handler QN — already dispatched synchronously by
-            // dispatch-write.ts's afterCommitHooks. Re-firing here would
-            // double-enqueue every existing handler-triggered job.
-            if (registry.getWriteHandler(event.type) || registry.getQueryHandler(event.type))
-                return;
-            // skip: no r.defineEvent registered under this type — nothing this
-            // consumer is responsible for.
-            if (!registry.getEvent(event.type))
-                return;
-            const user = {
-                id: event.metadata.userId,
-                tenantId: event.tenantId,
-                roles: [],
-            };
-            await jobRunner.handleEvent(event.type, event.payload, user, {
-                id: event.id,
-                headers: event.metadata.headers ?? {},
-            });
-        },
-    };
-}
 // --- Access-Invalidation Consumer (async, via event-dispatcher) ---
 //
 // This consumer is the last leg: it watches for the two event types that

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

@@ -10,7 +10,7 @@ export type { EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, Options
 export type { AccessRule } from "../engine/types/handlers.ts";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.ts";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.ts";
-export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessLink, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBulkAction, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, ListTableOptions, MetricNavigate, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, ToolbarAction, } from "../engine/types/screen.ts";
+export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, ActionFormScreenDefinition, ActionFormSuccessFact, ActionFormSuccessLink, ConfigEditScreenDefinition, CustomScreenDefinition, DashboardChartMarkerKind, DashboardChartPanel, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRefresh, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditScreenDefinition, EntityListFacetConfig, EntityListScreenDefinition, FieldAffix, FieldCondition, FieldFillAction, FieldIconKey, FieldRenderer, FormWidth, ListBulkAction, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListSortSpec, ListTableOptions, MetricNavigate, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListEmptyStateSpec, RelatedListEmptyStateVariant, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFallback, ScreenFallbackByReason, ScreenFallbackReason, ScreenSlots, ScreenVisibility, SecretMintConfirmStep, SecretMintScreenDefinition, SecretsEditScreenDefinition, ToolbarAction, } from "../engine/types/screen.ts";
 export { MAX_BULK_SELECTION } from "../engine/types/screen.ts";
 export type { TargetRef } from "../engine/types/target-ref.ts";
 export type { TreeAction } from "../engine/types/tree-node.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.393.0",
+  "version": "0.394.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -160,6 +160,10 @@
       "types": "./dist/consumer-cli.d.ts",
       "default": "./dist/consumer-cli.js"
     },
+    "./events-cli": {
+      "types": "./dist/events-cli.d.ts",
+      "default": "./dist/events-cli.js"
+    },
     "./upgrade-cli": {
       "types": "./dist/upgrade-cli.d.ts",
       "default": "./dist/upgrade-cli.js"
@@ -199,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.393.0",
+    "@cosmicdrift/kumiko-types": "0.394.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.1",
     "i18next": "^26.1.0",
@@ -221,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.393.0",
+    "@cosmicdrift/kumiko-testing": "0.394.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.2",
     "meilisearch": "^0.58.0",
@@ -361,6 +365,10 @@
         "types": "./dist/consumer-cli.d.ts",
         "default": "./dist/consumer-cli.js"
       },
+      "./events-cli": {
+        "types": "./dist/events-cli.d.ts",
+        "default": "./dist/events-cli.js"
+      },
       "./upgrade-cli": {
         "types": "./dist/upgrade-cli.d.ts",
         "default": "./dist/upgrade-cli.js"

package/src/changes.json

@@ -1,4 +1,46 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "AGENTS.md points app tests at kumiko-dev-server/testing",
+    "detail": "The Tests section told agents to import setupAppTestStack and seedTenant from @cosmicdrift/kumiko-testing, which does not export them; an agent that followed it got a missing-export error and had to copy the import from the scaffolded test. The section now names @cosmicdrift/kumiko-dev-server/testing. No code change."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "compliance profile labels are English",
+    "detail": "The labels of the built-in compliance profiles (eu-dsgvo, swiss-dsg, de-hr-dsgvo-hgb, minimal) were German in the English source; locale packages keep their option translations, and the compliance-profiles catalog now shows those translations instead of the raw source label. Authority names such as the de-hr authority contact stay as the authority calls itself."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Guides and screenshots for system check, inbound mail, billing and the 0.392 upgrade",
+    "detail": "New guides system-check, inbound-mail, billing-plans-and-checkout and upgrading-to-0-392 with screenshots from the use-all-bundled and styleguide specs. security-defaults splits the row level security section and adds a scope diagram, a raw access example and crossTenantReads; handler-context-and-embedded-fields gets a namespace table; auth-external-login, prod-bootstrap, screen-layout, renderer-widget-options, rbac-tenant-isolation and cap-overview cover returnTo, static login, MFA policies, requiredEnvFor, jobs readRoles, header actions, screen gates, previewOpenByDefault, bulk actions, export and showLimit. New user guide operator-screens, and the sample index wires matrix screenshots into the feature reference previews of admin-shell, audit, jobs, cap-overview, tenant-settings, delivery, compliance-profiles, account-security and sessions. No framework code change."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "events prune removes retired aggregate types from the event log",
+    "detail": "`@cosmicdrift/kumiko-framework/events-cli` exports `runEventsCli(argv, out, { features, rowLevelSecurity? })`. `events prune --aggregate-type <type> [--aggregate-type <type> ...]` reports events, aggregates and tenants per type; with `--apply` it deletes, in one transaction and in system scope, the events, snapshots, archive markers and dead letters of these types and empties the projections fed only by them. A projection that also reads other types makes the run refuse. Unknown or empty types fail without deleting anything. Use it when old events of a retired type break the rebuild of `schema apply`. Apps add `if (cmd === \"events\")` to `bin/kumiko.ts`; new scaffolds get it."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "beforeTransactionWhenNested skip lets a handler with a beforeTransaction phase run nested",
+    "detail": "`beforeTransactionWhenNested: \"skip\"` on a write handler lets a nested ctx.dispatch.write run it without the phase. `event.prepared` is then `undefined` (typed `TPrepared | undefined`) and the handler does that work inside its own transaction. Top-level commands still run the phase. Without the option a nested call stays rejected. Boot rejects the option without beforeTransaction and together with reserveBeforeTransaction; transaction \"perCommand\" is already rejected next to beforeTransaction."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "KMS outages surface as EncryptionUnavailableError",
+    "detail": "The PII key store configured with configurePiiSubjectKms wraps adapter failures (database, Key Manager, network) in EncryptionUnavailableError with code encryption_unavailable and HTTP status 503, exported from @cosmicdrift/kumiko-framework/crypto together with ENCRYPTION_UNAVAILABLE_CODE. Key-state errors (KeyNotFoundError, KeyErasedError, KeyAlreadyExistsError) keep their types. Callers can tell an outage, which they retry later, from a problem with the record."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "Live signals for entity names with uppercase runs reach the client",
+    "detail": "`toKebab` now lives once in `@cosmicdrift/kumiko-types/kebab-case` and is used by the server read-access keys, the qualified-name helpers and the renderer. Before, the renderer and server copies could diverge for names like `aiURLCheck`, so a screen subscribed to a name the server never signalled. Boot now fails when two entities of different features fold to the same key (`billing.period` and `billingPeriod`), instead of merging their read rules."
+  },
   {
     "version": "0.392.0",
     "type": "improvement",