@cosmicdrift/kumiko-framework 0.390.0 → 0.391.0

package/agents/features.md

@@ -8,6 +8,10 @@ Self-service account dashboard: MFA enrollment, recovery codes and the user's ow
 
 Requires: `sessions`, `auth-mfa`
 
+## admin-nav
+
+Administration group in the sidebar of this sample app.
+
 ## admin-shell
 
 Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.
@@ -538,12 +542,14 @@ Category: operations
 
 ## readiness
 
-One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`.
+One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`. `readiness:write:run-probes` runs the live probes features register with `r.probe` (mail, files, mailboxes, PDF service and more) as a job; the system-check screen shows the latest run and the history once `nav` is passed.
 
 Category: operations
 
 Requires: `config`, `secrets`
 
+Optional requires: `user`
+
 ## renderer-foundation
 
 Plugin registry for content rendering (mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block — add `renderer-mail-html` (or write a custom plugin via `r.useExtension("renderer", name, { kinds, render })`) rather than using this feature alone.

package/dist/api/index.d.ts

@@ -16,6 +16,8 @@ export type { JwtHelper } from "./jwt.ts";
 export { loadJwtSecretOrKeyring } from "./jwt.ts";
 export { publicOriginOf } from "./origin-middleware.ts";
 export type { PostAuthLandingArgs, PostAuthLandingResolver, } from "./post-auth-landing.ts";
+export type { TimedRunResult } from "./readiness.ts";
+export { runWithTimeout } from "./readiness.ts";
 export type { RedisSseBroker } from "./redis-sse-broker.ts";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
 export { readonlyRequestContext as requestContext } from "./request-context-scopes.ts";

package/dist/api/index.js

@@ -9,6 +9,7 @@ export { ExtraRouteRejection, signatureRoute } from "./extra-route.js";
 export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, } from "./http-cache.js";
 export { loadJwtSecretOrKeyring } from "./jwt.js";
 export { publicOriginOf } from "./origin-middleware.js";
+export { runWithTimeout } from "./readiness.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { readonlyRequestContext as requestContext } from "./request-context-scopes.js";
 export { buildRequestContextDataFromRequest } from "./request-id-middleware.js";

package/dist/api/readiness.d.ts

@@ -18,6 +18,17 @@ export type ReadinessProbeOptions = {
     readonly timeoutMs?: number;
 };
 export declare function createReadinessProbe(checks: readonly ReadinessCheck[], opts?: ReadinessProbeOptions): () => Promise<ReadinessResult>;
+export type TimedRunResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly latencyMs: number;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+    readonly timedOut: boolean;
+    readonly latencyMs: number;
+};
+export declare function runWithTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<TimedRunResult<T>>;
 export declare function dbPingCheck(db: DbConnection): ReadinessCheck;
 export declare function redisPingCheck(redis: Redis): ReadinessCheck;
 export declare function dispatcherLagCheck(db: DbConnection, consumerNames: readonly string[], maxLagEvents: bigint): ReadinessCheck;

package/dist/api/readiness.js

@@ -23,31 +23,29 @@ export function createReadinessProbe(checks, opts = {}) {
         };
     };
 }
-async function runOne(check, timeoutMs) {
+class TimeoutError extends Error {
+}
+export async function runWithTimeout(run, timeoutMs) {
     const start = performance.now();
+    const elapsedMs = () => Math.round(performance.now() - start);
     let timer;
     try {
-        await Promise.race([
-            check.run(),
+        const value = await Promise.race([
+            run(),
             new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+                timer = setTimeout(() => reject(new TimeoutError(`timeout after ${timeoutMs}ms`)), timeoutMs);
                 // Don't keep the event loop alive on a hung probe during shutdown.
                 timer.unref?.();
             }),
         ]);
-        return {
-            name: check.name,
-            ok: true,
-            latencyMs: Math.round(performance.now() - start),
-        };
+        return { ok: true, value, latencyMs: elapsedMs() };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+    catch (error) {
         return {
-            name: check.name,
             ok: false,
-            latencyMs: Math.round(performance.now() - start),
-            error: message,
+            error,
+            timedOut: error instanceof TimeoutError,
+            latencyMs: elapsedMs(),
         };
     }
     finally {
@@ -55,6 +53,17 @@ async function runOne(check, timeoutMs) {
             clearTimeout(timer);
     }
 }
+async function runOne(check, timeoutMs) {
+    const result = await runWithTimeout(check.run, timeoutMs);
+    if (result.ok)
+        return { name: check.name, ok: true, latencyMs: result.latencyMs };
+    return {
+        name: check.name,
+        ok: false,
+        latencyMs: result.latencyMs,
+        error: result.error instanceof Error ? result.error.message : String(result.error),
+    };
+}
 // --- Standard checks --------------------------------------------------------
 export function dbPingCheck(db) {
     return {

package/dist/compliance/sub-processors.js

@@ -16,7 +16,7 @@
 // SubProcessor has no "removed" state yet: a removed entry is deleted from
 // the array, so until the notification cron exists a removal is documented
 // only in the changelog. Removed so far: Mailbox.org (mailbox hosting),
-// replaced by ALL-INKL.COM.
+// replaced by ALL-INKL.COM, and Cloudflare (DNS/CDN), replaced by Hetzner DNS.
 /**
  * Platform-wide sub-processor list.
  *
@@ -33,16 +33,6 @@ export const KUMIKO_SUB_PROCESSORS = [
         appliesTo: ["all-tiers"],
         status: "active",
     },
-    {
-        name: "Cloudflare, Inc.",
-        purpose: "DNS, CDN, DDoS-Protection, WAF",
-        region: "Global (US-headquartered)",
-        dpa: "https://www.cloudflare.com/cloudflare-customer-dpa",
-        addedAt: "2024-01-01",
-        appliesTo: ["all-tiers"],
-        sccRequired: true,
-        status: "active",
-    },
     {
         name: "Sendinblue SAS (Brevo)",
         purpose: "Transactional Email Delivery",

package/dist/db/driver-value-preparation.js

@@ -65,9 +65,30 @@ const INTEGER_PG_TYPES = new Set([
 export function instantToTimestamptzParam(instant) {
     return Temporal.Instant.fromEpochMilliseconds(instant.epochMilliseconds).toString();
 }
+function instantOfIsoString(value) {
+    try {
+        return Temporal.Instant.from(value);
+    }
+    catch {
+        // skip: not an ISO instant, Postgres parses (or rejects) the text itself
+        return undefined;
+    }
+}
+// Event payloads carry instants as ISO strings with microseconds; a projection rebuild binds them
+// as-is, so without the same truncation the replayed row differs from the live one.
+function timestamptzInstantOf(value) {
+    if (isTemporalInstant(value))
+        return value;
+    if (typeof value === "string")
+        return instantOfIsoString(value);
+    return undefined;
+}
 function prepareDriverNeutralScalar(value, pgType) {
-    if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
-        return { kind: "param", sql: "", bound: instantToTimestamptzParam(value) };
+    if (pgType === "timestamptz" || pgType === "timestamptz(3)") {
+        const instant = timestamptzInstantOf(value);
+        if (instant !== undefined) {
+            return { kind: "param", sql: "", bound: instantToTimestamptzParam(instant) };
+        }
     }
     // Sent as text, so Postgres rejects 3.5 for an integer column instead of rounding it.
     if (typeof value === "number" && pgType !== undefined && INTEGER_PG_TYPES.has(pgType)) {

package/dist/db/queries/test-stack.js

@@ -1,5 +1,6 @@
 import { extractPgError } from "../pg-error.js";
 import { asRawClient } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 import { PROJECTION_REBUILD_SCHEMA } from "./shadow-swap.js";
 import { quoteTableIdent } from "./table-ops.js";
 // Re-exported for back-compat — the generic DDL helpers moved to ./ddl so
@@ -89,7 +90,7 @@ export async function transferPublicSchemaOwnership(db, owner) {
        JOIN pg_namespace n ON n.oid = c.relnamespace
        JOIN pg_roles r ON r.oid = c.relowner
       WHERE n.nspname = ANY($2::text[]) AND c.relkind IN ('r', 'p', 'S', 'v', 'm') AND r.rolname <> $1
-        AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype IN ('a', 'i'))`, [owner, ownedSchemas]);
+        AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype IN ('a', 'i'))`, [owner, toPostgresArrayLiteral(ownedSchemas)]);
     for (const { nspname, relname, relkind } of relations) {
         const kind = OWNED_RELATION_KINDS[relkind];
         if (kind === undefined)

package/dist/db/row-level-security-boot-check.d.ts

@@ -1,5 +1,6 @@
 import { type KnownTables } from "./known-table-names.ts";
 import type { AnyDb } from "./query.ts";
 import type { RowLevelSecurityMode } from "./render-rls-ddl.ts";
-export declare function assertRowLevelSecurityTableState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables): Promise<void>;
+export type RowLevelSecurityCheckScope = "database" | "declared tables";
+export declare function assertRowLevelSecurityTableState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables, scope?: RowLevelSecurityCheckScope): Promise<void>;
 export declare function assertRowLevelSecurityBootState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables): Promise<void>;

package/dist/db/row-level-security-boot-check.js

@@ -28,8 +28,9 @@ async function assertEnforcingRole(db) {
 function listingOf(entries) {
     return entries.map((entry) => `${entry.table} (${entry.missing.join(", ")})`).join("; ");
 }
-async function assertAllTenantTablesProtected(db, knownTables) {
+async function assertAllTenantTablesProtected(db, knownTables, scope) {
     const incomplete = (await readTenantTablesRowLevelSecurity(db))
+        .filter((table) => scope === "database" || knownTables.has(table.tableName))
         .map((table) => ({ table: table.tableName, missing: missingPartsOf(table) }))
         .filter((entry) => entry.missing.length > 0);
     // skip: every tenant table is protected
@@ -59,8 +60,8 @@ async function assertAllTenantTablesProtected(db, knownTables) {
         message: `rowLevelSecurity is "on" but tenant tables lack row-level security. ${sections.join(" ")}`,
     });
 }
-async function assertNoLiveRowLevelSecurity(db) {
-    const tables = await readTablesWithRowLevelSecurityEnabled(db);
+async function assertNoLiveRowLevelSecurity(db, knownTables, scope) {
+    const tables = (await readTablesWithRowLevelSecurityEnabled(db)).filter((table) => scope === "database" || knownTables.has(table));
     // skip: no live row-level security to disable
     if (tables.length === 0)
         return;
@@ -70,13 +71,13 @@ async function assertNoLiveRowLevelSecurity(db) {
 }
 // Table state only, no role check: the role is a runtime property of the boot connection, so tools
 // that connect with another role (CI, `schema validate`) use this one.
-export async function assertRowLevelSecurityTableState(db, mode, knownTables) {
+export async function assertRowLevelSecurityTableState(db, mode, knownTables, scope = "database") {
     if (mode === "off") {
-        await assertNoLiveRowLevelSecurity(db);
+        await assertNoLiveRowLevelSecurity(db, knownTables, scope);
         // skip: off-mode check done
         return;
     }
-    await assertAllTenantTablesProtected(db, knownTables);
+    await assertAllTenantTablesProtected(db, knownTables, scope);
 }
 export async function assertRowLevelSecurityBootState(db, mode, knownTables) {
     if (mode === "on")

package/dist/engine/boot-validator/screens-lists.d.ts

@@ -43,6 +43,10 @@ export declare function validateColumnRendererForm(featureName: string, screenId
     readonly field: string;
     readonly renderer?: unknown;
 }): void;
+export declare function validateEnumOptionTones(prefix: string, column: {
+    readonly field: string;
+    readonly renderer?: unknown;
+}): void;
 export declare function assertRefTargetRegistered(prefix: string, subject: string, refTarget: string, currentFeatureName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
 export declare function validateListFacets(prefix: string, facets: readonly ListFacetSpec[], columns: readonly ListColumnSpec[], currentFeatureName: string, featureMap: ReadonlyMap<string, FeatureDefinition>): void;
 export {};

package/dist/engine/boot-validator/screens-lists.js

@@ -1,3 +1,5 @@
+import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { qualifyEntityName } from "../qualified-name.js";
@@ -6,6 +8,7 @@ import { validateListBulkActions } from "./list-bulk-actions.js";
 import { validateListTableOptions } from "./list-table-options.js";
 import { validateRelatedListGroupingRules } from "./related-list-table-rules.js";
 import { assertWriteHandlerRegistered, isRowClickAction, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateClientActionName, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
+import { isSelectOptionTone } from "./select-option-tone.js";
 // validateScreenHasNavArea runs once per screen; the index is built once per
 // featureMap (immutable during boot) instead of re-scanning every feature each call.
 const navAreaIndexByFeatureMap = new WeakMap();
@@ -91,6 +94,7 @@ export function validateRelatedListSection(args) {
     }
     for (const col of section.columns) {
         const normalizedCol = normalizeListColumn(col);
+        validateEnumOptionTones(`[Feature ${featureName}] ${where}`, normalizedCol);
         if (normalizedCol.refEntity !== undefined) {
             assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, `column "${normalizedCol.field}" (refEntity)`, normalizedCol.refEntity, featureName, featureMap);
         }
@@ -226,6 +230,7 @@ export function rejectInertColumnSortable(featureName, screenId, screenType, col
 // string. A key omitted on the client only triggers a warning, not a boot
 // failure.
 export function validateColumnRendererForm(featureName, screenId, column) {
+    validateEnumOptionTones(`[Feature ${featureName}] Screen "${screenId}"`, column);
     const renderer = column.renderer;
     // skip: only the PlatformComponent form ({ react: { __component: "..." } })
     // is validated structurally. Function, string-QN and null/undefined
@@ -254,6 +259,26 @@ export function validateColumnRendererForm(featureName, screenId, column) {
             `a client-side columnRenderers entry.`);
     }
 }
+// A typo'd tone would silently fall back to the neutral pill.
+export function validateEnumOptionTones(prefix, column) {
+    const { renderer } = column;
+    const isEnumOption = typeof renderer === "object" &&
+        renderer !== null &&
+        propertyOf(renderer, "format") === "enumOption";
+    const tones = isEnumOption ? propertyOf(renderer, "tones") : undefined;
+    // skip: only an enumOption column with tones has tones to check.
+    if (tones === undefined)
+        return;
+    const invalid = typeof tones !== "object" || tones === null
+        ? [String(tones)]
+        : Object.values(tones)
+            .filter((tone) => !isSelectOptionTone(tone))
+            .map(String);
+    if (invalid.length > 0) {
+        throw new Error(`${prefix} column "${column.field}" has enumOption tones ${invalid.join(", ")} — ` +
+            `expected one of ${SELECT_OPTION_TONES.join(", ")}.`);
+    }
+}
 // Shared entity-target resolution for reference facets, refEntity columns
 // (projectionList/relatedList) and refEntity fields (projectionDetail).
 export function assertRefTargetRegistered(prefix, subject, refTarget, currentFeatureName, featureMap) {

package/dist/engine/define-feature.js

@@ -1,6 +1,7 @@
 import { createInitialFeatureBuilderState } from "./feature-builder-state.js";
 import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs.js";
 import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
+import { buildProbeMethods } from "./feature-probes.js";
 import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
 import { isObjectArgument, throwObjectArgumentRequired, unwrapArrayForm } from "./object-form.js";
 // `TExports` lets the setup callback hand back a typed object that
@@ -89,6 +90,7 @@ export function defineFeature(name, setup, settings) {
         ...buildEntityHandlerMethods(state, name),
         ...buildConfigEventsJobsMethods(state, name),
         ...buildUiExtensionsMethods(state, name),
+        ...buildProbeMethods(state, name),
     };
     const exports = setup(registrar); // @cast-boundary engine-bridge
     return {
@@ -147,6 +149,7 @@ export function defineFeature(name, setup, settings) {
         metrics: state.metrics,
         secretKeys: state.secretKeys,
         secretNamespaces: state.secretNamespaces,
+        ...(Object.keys(state.probes).length > 0 && { probes: state.probes }),
         projections: state.projections,
         entityProjectionExtensions: state.entityProjectionExtensions,
         multiStreamProjections: state.multiStreamProjections,

package/dist/engine/feature-builder-state.d.ts

@@ -3,6 +3,7 @@ import type { BootCheckFn, FeatureMetricDef, SecretKeyDefinition, SecretNamespac
 import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { AuthClaimsFn, ClaimKeyDefinition, EventDef, EventMigrationDef, QueryHandlerDef, StreamHandlerDef, WriteHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
 import type { LifecycleHookFn, OwnedFn, PhasedHook, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, SearchPayloadContributorFn, ValidationHookFn } from "@cosmicdrift/kumiko-types/hooks";
+import type { ProbeDefinition } from "@cosmicdrift/kumiko-types/probe";
 import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "@cosmicdrift/kumiko-types/projection";
 import type { RelationDefinition } from "@cosmicdrift/kumiko-types/relations";
 import type { TreeActionDef } from "@cosmicdrift/kumiko-types/tree-node";
@@ -49,6 +50,7 @@ export type FeatureBuilderState = {
     metrics: Record<string, FeatureMetricDef>;
     secretKeys: Record<string, SecretKeyDefinition>;
     secretNamespaces: Record<string, SecretNamespaceDefinition>;
+    probes: Record<string, ProbeDefinition>;
     projections: Record<string, ProjectionDefinition>;
     multiStreamProjections: Record<string, MultiStreamProjectionDefinition>;
     entityProjectionExtensions: Record<string, EntityProjectionExtension[]>;

package/dist/engine/feature-builder-state.js

@@ -42,6 +42,7 @@ export function createInitialFeatureBuilderState() {
         metrics: {},
         secretKeys: {},
         secretNamespaces: {},
+        probes: {},
         projections: {},
         multiStreamProjections: {},
         entityProjectionExtensions: {},

package/dist/engine/feature-probes.d.ts

@@ -0,0 +1,5 @@
+import type { ProbeOptions } from "@cosmicdrift/kumiko-types/probe";
+import type { FeatureBuilderState } from "./feature-builder-state.ts";
+export declare function buildProbeMethods(state: FeatureBuilderState, featureName: string): {
+    probe(options: ProbeOptions): void;
+};

package/dist/engine/feature-probes.js

@@ -0,0 +1,46 @@
+import { isKebabSegment, QnTypes, qn, toKebab } from "./qualified-name.js";
+const PROBE_SCOPES = ["tenant", "system"];
+const PROBE_COSTS = ["free", "paid"];
+function assertValidProbe(featureName, options) {
+    const prefix = `[Feature ${featureName}] r.probe()`;
+    if (typeof options.name !== "string" || options.name.length === 0) {
+        throw new Error(`${prefix}: name must be a non-empty string`);
+    }
+    if (!isKebabSegment(options.name)) {
+        throw new Error(`${prefix}: name "${options.name}" must be kebab-case`);
+    }
+    if (!PROBE_SCOPES.includes(options.scope)) {
+        throw new Error(`${prefix} "${options.name}": scope must be one of ${PROBE_SCOPES.join(", ")}`);
+    }
+    if (!PROBE_COSTS.includes(options.cost)) {
+        throw new Error(`${prefix} "${options.name}": cost must be one of ${PROBE_COSTS.join(", ")}`);
+    }
+    for (const field of ["area", "label"]) {
+        if (typeof options[field] !== "string" || options[field].length === 0) {
+            throw new Error(`${prefix} "${options.name}": ${field} must be a non-empty i18n key`);
+        }
+    }
+    if (options.timeoutMs !== undefined && !(options.timeoutMs > 0)) {
+        throw new Error(`${prefix} "${options.name}": timeoutMs must be > 0`);
+    }
+    if (typeof options.run !== "function") {
+        throw new Error(`${prefix} "${options.name}": run must be a function`);
+    }
+    if (options.targets !== undefined && typeof options.targets !== "function") {
+        throw new Error(`${prefix} "${options.name}": targets must be a function`);
+    }
+}
+export function buildProbeMethods(state, featureName) {
+    return {
+        probe(options) {
+            assertValidProbe(featureName, options);
+            if (state.probes[options.name]) {
+                throw new Error(`[Feature ${featureName}] Probe "${options.name}" already registered. Probe names must be unique per feature.`);
+            }
+            state.probes[options.name] = {
+                ...options,
+                qualifiedName: qn(toKebab(featureName), QnTypes.probe, options.name),
+            };
+        },
+    };
+}

package/dist/engine/index.d.ts

@@ -11,6 +11,7 @@ export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN,
 export type { DeleteContext, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SaveContext, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { EntityId } from "@cosmicdrift/kumiko-types/identifiers";
 export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@cosmicdrift/kumiko-types/nav";
+export type { ProbeContext, ProbeCost, ProbeDefinition, ProbeOptions, ProbeScope, ProbeTarget, ProbeText, ProbeVerdict, } from "@cosmicdrift/kumiko-types/probe";
 export type { MspErrorMode, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, } from "@cosmicdrift/kumiko-types/projection";
 export type { RelationDefinition } from "@cosmicdrift/kumiko-types/relations";
 export type { ActionFormScreenDefinition, BundledListsOptions, ConfigEditScreenDefinition, DashboardCustomPanel, DashboardI18nText, EditFieldSpec, EditRelatedListSection, EditSectionSpec, EntityEditScreenDefinition, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, ListColumnSpec, ListFacetSpec, ListTableOptions, MetricNavigate, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RowAction, RowActionWriteHandler, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
@@ -70,6 +71,7 @@ export { from, normalizeAccessEntry, } from "./ownership.ts";
 export { pagedListSchema, pageRows, } from "./paged-list.ts";
 export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target.ts";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline.ts";
+export { ProbeFailure } from "./probe-failure.ts";
 export { projectAppSchemaForRoles } from "./project-app-schema-for-roles.ts";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers.ts";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.ts";

package/dist/engine/index.js

@@ -55,6 +55,7 @@ export { from, normalizeAccessEntry, } from "./ownership.js";
 export { pagedListSchema, pageRows, } from "./paged-list.js";
 export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target.js";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline.js";
+export { ProbeFailure } from "./probe-failure.js";
 export { projectAppSchemaForRoles } from "./project-app-schema-for-roles.js";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers.js";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name.js";

package/dist/engine/probe-failure.d.ts

@@ -0,0 +1,5 @@
+import type { ProbeText } from "@cosmicdrift/kumiko-types/probe";
+export declare class ProbeFailure extends Error {
+    readonly text: ProbeText;
+    constructor(text: ProbeText);
+}

package/dist/engine/probe-failure.js

@@ -0,0 +1,9 @@
+// Thrown by a probe to report a translatable failure; any other error maps to a generic text so raw messages never reach the run.
+export class ProbeFailure extends Error {
+    text;
+    constructor(text) {
+        super(text.key);
+        this.text = text;
+        this.name = "ProbeFailure";
+    }
+}

package/dist/engine/qualified-name.d.ts

@@ -10,6 +10,7 @@ export declare const QnTypes: {
     readonly secret: "secret";
     readonly screen: "screen";
     readonly nav: "nav";
+    readonly probe: "probe";
 };
 export type QnType = string;
 export type ParsedQn = {

package/dist/engine/qualified-name.js

@@ -22,6 +22,7 @@ export const QnTypes = {
     secret: "secret",
     screen: "screen",
     nav: "nav",
+    probe: "probe",
 };
 const QN_SEGMENT = /^[a-z][a-z0-9-]*$/;
 function validateSegment(value, label, context) {

package/dist/es-ops/operations-schema.js

@@ -6,6 +6,8 @@
 import { index, integer, table as pgTable, sql, text, timestamp } from "../db/dialect.js";
 // sql now comes from native dialect
 import { tableExists } from "../db/index.js";
+import { acquireNamespacedAdvisoryLock } from "../db/queries/advisory-lock.js";
+import { ES_OPS_ADVISORY_LOCK_KEY } from "../db/queries/es-ops.js";
 import { unsafePushTables } from "../db/table-push.js";
 export const esOperationsTable = pgTable("kumiko_es_operations", {
     // Filename without extension serves as ID. Chronologically sortable
@@ -25,10 +27,17 @@ export const esOperationsTable = pgTable("kumiko_es_operations", {
 }, (t) => ({
     typeIdx: index("kumiko_es_operations_type_idx").on(t.operationType),
 }));
-// Convenience for tests + boot-time setup (idempotent). Mirrors the
-// createEventsTable pattern in event-store/events-schema.ts.
+const ES_OPERATIONS_DDL_LOCK_KEY = "kumiko_es_operations:ddl";
+// Replicas boot concurrently and CREATE TABLE IF NOT EXISTS is not race-safe: the loser trips
+// pg_type_typname_nsp_index. The lock transaction only carries the lock; the DDL runs on `db`.
 export async function createEsOperationsTable(db) {
-    if (!(await tableExists(db, "public.kumiko_es_operations"))) {
-        await unsafePushTables(db, { kumikoEsOperations: esOperationsTable });
-    }
+    // skip: the table exists, no lock needed on the common boot path.
+    if (await tableExists(db, "public.kumiko_es_operations"))
+        return;
+    await db.begin(async (lockTx) => {
+        await acquireNamespacedAdvisoryLock(lockTx, ES_OPS_ADVISORY_LOCK_KEY, ES_OPERATIONS_DDL_LOCK_KEY);
+        if (!(await tableExists(db, "public.kumiko_es_operations"))) {
+            await unsafePushTables(db, { kumikoEsOperations: esOperationsTable });
+        }
+    });
 }

package/dist/schema-cli/shared.d.ts

@@ -5,7 +5,12 @@ export type SchemaCliOut = {
     readonly log: (line: string) => void;
     readonly err: (line: string) => void;
 };
-export type RunSchemaCliOptions = {
+type RunSchemaCliRowLevelSecurityOption = {
+    /** The mode the app's runtime boots with (`AppConfig.rowLevelSecurity`). Wins over the schema
+     *  file, so `apply` heals the same mode the boot check enforces. */
+    readonly rowLevelSecurity?: RowLevelSecurityMode;
+};
+export type RunSchemaCliOptions = RunSchemaCliRowLevelSecurityOption & ({
     readonly features?: undefined;
     readonly kmsSlots?: undefined;
 } | {
@@ -17,7 +22,7 @@ export type RunSchemaCliOptions = {
      *  `[]` when the app wires none. This CLI parses no env schema, so the
      *  rebuild's KMS wiring cannot derive them itself. */
     readonly kmsSlots: readonly string[];
-};
+});
 export type SchemaCliContext = {
     readonly argv: readonly string[];
     readonly out: SchemaCliOut;
@@ -41,3 +46,4 @@ export declare function loadSchemaModOrReport(ctx: SchemaCliContext): Promise<Sc
 export declare function loadRowLevelSecurityModeOrReport(ctx: SchemaCliContext): Promise<RowLevelSecurityMode | undefined>;
 export declare function readDatabaseUrlOrReport(out: SchemaCliOut): string | undefined;
 export declare function migrationsDirExistsOrReport(ctx: SchemaCliContext): boolean;
+export {};

package/dist/schema-cli/shared.js

@@ -91,11 +91,14 @@ export async function loadSchemaModOrReport(ctx) {
     }
 }
 // `apply` needs only the mode: migrations and rebuilds on a role that RLS binds see nothing unless
-// the connection runs in system scope, which only an "on" connection sets. Without a schema file
-// (dev CLI against a bare checkout) there is nothing to enforce.
+// the connection runs in system scope, which only an "on" connection sets. The prod image ships no
+// kumiko/schema.ts, so without one apply falls back to the runtime's default instead of "off":
+// otherwise the framework tables stay unhealed and the boot check of an "on" app fails.
 export async function loadRowLevelSecurityModeOrReport(ctx) {
+    if (ctx.options.rowLevelSecurity !== undefined)
+        return ctx.options.rowLevelSecurity;
     if (!existsSync(ctx.schemaFile))
-        return "off";
+        return DEFAULT_ROW_LEVEL_SECURITY_MODE;
     return (await loadSchemaModOrReport(ctx))?.rowLevelSecurity;
 }
 export function readDatabaseUrlOrReport(out) {

package/dist/schema-cli/validate-command.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { assertRowLevelSecurityTableState, createDbConnection, generateMigration, } from "../db/index.js";
-import { knownTablesOf } from "../db/known-table-names.js";
+import { isLiveFrameworkTable } from "../db/known-table-names.js";
 import { readMigrationSqlTexts } from "../db/migrate-runner.js";
 import { diffReplayAgainstSnapshot, replayMigrationsDir } from "../db/replay-migration-sql.js";
 import { validateBoot } from "../engine/boot-validator.js";
@@ -62,31 +62,27 @@ function checkBootValidity(out, schemaMod) {
         return false;
     }
 }
+function declaredTablesOf(schemaMod) {
+    const names = new Set(schemaMod.entityMetas.map((meta) => meta.tableName));
+    return { has: (tableName) => names.has(tableName) || isLiveFrameworkTable(tableName) };
+}
 // 4. Live row-level security table state — the table half of the boot check. Only with a DATABASE_URL;
-// without one the command stays database-free.
+// without one the command stays database-free. Scoped to the tables kumiko/schema.ts declares plus the
+// framework tables, because a local DATABASE_URL may point at a dev database several apps share.
 async function checkLiveRowLevelSecurity(out, schemaMod) {
     const dbUrl = process.env["DATABASE_URL"];
     if (!dbUrl) {
         out.log("  · row-level security: skipped — set DATABASE_URL to check the live database.");
         return true;
     }
-    let features;
-    try {
-        features = featureDefinitionsOf(schemaMod.features);
-    }
-    catch {
-        // skip: the boot check already reported the unreadable FEATURES export
-        return true;
-    }
-    const knownTables = features === undefined ? { has: () => true } : knownTablesOf(features);
     const { db, close } = createDbConnection({
         url: dbUrl,
         maxConnections: 1,
         rowLevelSecurity: schemaMod.rowLevelSecurity,
     });
     try {
-        await assertRowLevelSecurityTableState(db, schemaMod.rowLevelSecurity, knownTables);
-        out.log("  ✓ row-level security: live database matches the configured mode");
+        await assertRowLevelSecurityTableState(db, schemaMod.rowLevelSecurity, declaredTablesOf(schemaMod), "declared tables");
+        out.log("  ✓ row-level security: live database matches the configured mode for this app's tables and the framework tables (tables of other apps sharing the database are not checked)");
         return true;
     }
     catch (e) {

package/dist/upgrade-cli.d.ts

@@ -4,4 +4,5 @@ export declare function findFeaturesDirs(cwd: string): string[];
 export declare function resolveCodemodScript(repoRoot: string, codemodField: string | undefined): string | null;
 export declare function runUpgradeCli(argv: readonly string[], cwd: string, out: UpgradeCliOut, options?: {
     readonly repoRoot?: string;
+    readonly codemodResolveFrom?: string;
 }): Promise<number>;

package/dist/upgrade-cli.js

@@ -213,6 +213,10 @@ function resolveCodemodScriptAt(codemodScriptsRoot, codemodField) {
     }
     return resolved;
 }
+function findCodemodScriptsRootPreferring(resolveFrom, repoRoot) {
+    const own = resolveFrom === undefined ? null : findCodemodScriptsRoot(resolveFrom);
+    return own ?? findCodemodScriptsRoot(repoRoot);
+}
 export function resolveCodemodScript(repoRoot, codemodField) {
     const scriptsRoot = findCodemodScriptsRoot(repoRoot);
     if (!scriptsRoot)
@@ -388,7 +392,7 @@ function writePartialMarker(out, targetDir, pending, manualEntries, failedVersio
 // even with zero pending entries, so an already-current app still gets a
 // bootstrap marker recording its installed version.
 // kumiko-lint-ignore complexity-budget sequential codemod runner with zero-pending bootstrap marker
-async function applyCodemods(out, pending, repoRoot, targetDir, dryRun, 
+async function applyCodemods(out, pending, codemodLocation, targetDir, dryRun, 
 // Installed version for the zero-pending bootstrap marker — never a
 // `--from` filter override (that would permanently skip real pending
 // codemods once the CI guard compares against the fake marker).
@@ -443,14 +447,16 @@ markerVersion, previous, fromVersion, manualDetails) {
         }
         return 0;
     }
-    const codemodScriptsRoot = findCodemodScriptsRoot(repoRoot);
+    const { repoRoot, resolveFrom: codemodResolveFrom } = codemodLocation;
+    const codemodScriptsRoot = findCodemodScriptsRootPreferring(codemodResolveFrom, repoRoot);
     if (codemodScriptsRoot === null) {
-        out.err(`  ✗ could not locate @cosmicdrift/kumiko-feature-ast/src/scripts/codemod — is @cosmicdrift/kumiko-cli or @cosmicdrift/kumiko-dev-server installed? searched from ${repoRoot} upward`);
+        const searched = codemodResolveFrom === undefined ? repoRoot : `${codemodResolveFrom} and ${repoRoot}`;
+        out.err(`  ✗ could not locate @cosmicdrift/kumiko-feature-ast/src/scripts/codemod — is @cosmicdrift/kumiko-cli or @cosmicdrift/kumiko-dev-server installed? searched from ${searched} upward`);
         return 1;
     }
     const ran = [];
     for (const e of codemodEntries) {
-        const scriptPath = resolveCodemodScript(repoRoot, e.codemod);
+        const scriptPath = resolveCodemodScriptAt(codemodScriptsRoot, e.codemod);
         if (!scriptPath) {
             out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
             if (!dryRun)
@@ -681,7 +687,7 @@ function planUpgrade(args, cwd, targetDir) {
         value: { ...baseline.value, targetInstalledVersion, allEntries, pending },
     };
 }
-async function applyPlannedUpgrade(out, args, plan, repoRoot, targetDir) {
+async function applyPlannedUpgrade(out, args, plan, codemodLocation, targetDir) {
     // Marker must reflect what is actually installed under the target (or
     // cwd), not the filter baseline above — otherwise CI stays green forever.
     const markerVersion = plan.targetInstalledVersion;
@@ -690,7 +696,7 @@ async function applyPlannedUpgrade(out, args, plan, repoRoot, targetDir) {
         return failUpgrade(out, `Could not detect the installed Kumiko version under ${targetDir}.`, "Refusing to write an upgrade marker without it (--from is only a filter).");
     }
     out.log("");
-    const code = await applyCodemods(out, plan.pending, repoRoot, targetDir, dryRun, markerVersion ?? plan.currentVersion, carryOf(plan.markerRead), plan.currentVersion, getFlag(args, "verbose") ? manualDetailsOf(plan.allEntries) : undefined);
+    const code = await applyCodemods(out, plan.pending, codemodLocation, targetDir, dryRun, markerVersion ?? plan.currentVersion, carryOf(plan.markerRead), plan.currentVersion, getFlag(args, "verbose") ? manualDetailsOf(plan.allEntries) : undefined);
     out.log("");
     return code;
 }
@@ -802,7 +808,13 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     if (planned.kind === "error")
         return failUpgrade(out, ...planned.lines);
     if (getFlag(args, "apply")) {
-        return applyPlannedUpgrade(out, args, planned.value, options?.repoRoot ?? cwd, targetDir);
+        const codemodLocation = {
+            repoRoot: options?.repoRoot ?? cwd,
+            ...(options?.codemodResolveFrom !== undefined && {
+                resolveFrom: options.codemodResolveFrom,
+            }),
+        };
+        return applyPlannedUpgrade(out, args, planned.value, codemodLocation, targetDir);
     }
     if (getFlag(args, "json"))
         return reportUpgradeJson(out, planned.value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.390.0",
+  "version": "0.391.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.390.0",
+    "@cosmicdrift/kumiko-types": "0.391.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.1",
     "i18next": "^26.1.0",
@@ -209,7 +209,7 @@
     "temporal-polyfill": "^0.3.2",
     "uuid": "^14.0.0",
     "write-excel-file": "^4.1.1",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "peerDependencies": {
     "bun-types": "^1.4.4",
@@ -221,7 +221,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.390.0",
+    "@cosmicdrift/kumiko-testing": "0.391.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.2",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,58 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "fix",
+    "title": "Concurrent boots create kumiko_es_operations without a race",
+    "detail": "CREATE TABLE IF NOT EXISTS is not race-safe in Postgres, so replicas booting against a fresh database could fail on pg_type_typname_nsp_index. createEsOperationsTable now takes an advisory lock and checks again before it creates the table."
+  },
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "r.probe registers live readiness probes with a per-probe timeout",
+    "detail": "A feature registers a probe with r.probe({ name, scope, cost, area, label, timeoutMs?, targets?, run }). scope \"system\" probes run only for SystemAdmins, \"tenant\" probes also for TenantAdmins of that tenant; cost \"paid\" probes run only when the caller asks for them. targets splits one probe into one result per target, such as one per mailbox. runWithTimeout from the api barrel is the shared timeout runner the readiness checks and probe runs use. A probe's context holds db, registry, obs, tz and services plus the run fields; the run job's dispatch, event emitter and escape-hatch powers stay with the job. The readiness status query still makes no network call."
+  },
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "The boot validator checks enumOption tones",
+    "detail": "A list column with renderer { format: \"enumOption\", tones } fails boot when a tone is not one of the select-option tones."
+  },
+  {
+    "version": "0.391.0",
+    "type": "fix",
+    "title": "Cloudflare is no longer listed as a sub-processor",
+    "detail": "DNS moved to Hetzner, so Cloudflare, Inc. no longer processes data for the platform. The entry is gone from KUMIKO_SUB_PROCESSORS, which means it is missing from /api/compliance/sub-processors and from the sub-processor RSS feed."
+  },
+  {
+    "version": "0.390.1",
+    "type": "fix",
+    "title": "schema apply in the production image uses the runtime's row-level security mode",
+    "detail": "The app image ships only kumiko/migrations, not kumiko/schema.ts. Without the schema file `schema apply` ran with row-level security \"off\", so kumiko_events, kumiko_snapshots and kumiko_archived_streams were not healed and the boot of an app in \"on\" mode (the default) failed with \"framework tables without it\". Without a schema file apply now uses the same default as runProdApp. RunSchemaCliOptions takes an optional rowLevelSecurity, which wins over the schema file; the scaffolded bin/kumiko.ts passes appConfig.rowLevelSecurity, like bin/main.ts does for runProdApp. Apps that do not set rowLevelSecurity need no change. An app that sets rowLevelSecurity \"off\" and keeps a hand-written bin/kumiko.ts must pass rowLevelSecurity: \"off\" to runSchemaCli, otherwise apply enables row-level security on the framework tables and the app's \"off\" boot check fails."
+  },
+  {
+    "version": "0.390.1",
+    "type": "fix",
+    "title": "Projection rebuilds no longer report drift on timestamptz columns",
+    "detail": "Event payloads keep the microseconds of an instant, the live write stores milliseconds. A rebuild bound the payload's ISO string unchanged and wrote a different value, which the shadow diff reported as column drift. ISO instant strings bound to a timestamptz column are now truncated to milliseconds like Temporal.Instant values."
+  },
+  {
+    "version": "0.390.1",
+    "type": "improvement",
+    "title": "The live row-level security check of `kumiko check` covers only the app's own tables",
+    "detail": "`schema validate` (the boot step of `kumiko check`) checks the live database when DATABASE_URL is set. On a dev database several apps share it failed on the other apps' tables. It now checks the tables kumiko/schema.ts declares plus the framework tables; tables no feature declares any more are still reported by the boot check, which runs against the app's own database. An unreachable database still fails the check."
+  },
+  {
+    "version": "0.390.1",
+    "type": "fix",
+    "title": "kumiko-upgrade runs the codemods of its own feature-ast install",
+    "detail": "The kumiko-upgrade bins of kumiko-cli and kumiko-dev-server now look for the codemod scripts from their own package first, so a feature-ast copy hoisted above the app (for example in a workspace parent) can no longer supply codemods of another version. runUpgradeCli takes an optional codemodResolveFrom for that; without it the search still starts at the repo root."
+  },
+  {
+    "version": "0.390.1",
+    "type": "fix",
+    "title": "zod range moved to ^4.6.7",
+    "detail": "All framework packages and the scaffold template require zod ^4.6.7, which fixes GHSA-MRHX-C7XC-M3W5."
+  },
   {
     "version": "0.390.0",
     "type": "fix",