@cosmicdrift/kumiko-framework 0.390.1 → 0.391.1

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/row-level-security-boot-check.js

@@ -42,17 +42,17 @@ async function assertAllTenantTablesProtected(db, knownTables, scope) {
     const sections = [
         ...(frameworkTables.length > 0
             ? [
-                `framework tables without it: ${listingOf(frameworkTables)}. Run \`kumiko schema apply\`: it adds the missing policies to the framework tables (\`kumiko schema generate\` reports no changes for them).`,
+                `framework tables without it: ${listingOf(frameworkTables)}. Run \`bun kumiko-schema apply\`: it adds the missing policies to the framework tables (\`bun kumiko-schema generate\` reports no changes for them).`,
             ]
             : []),
         ...(known.length > 0
             ? [
-                `tables of this app without it: ${listingOf(known)}. Run \`kumiko schema generate\` and apply the migration.`,
+                `tables of this app without it: ${listingOf(known)}. Run \`bun kumiko-schema generate\` and apply the migration.`,
             ]
             : []),
         ...(orphaned.length > 0
             ? [
-                `tables no feature declares anymore: ${listingOf(orphaned)}. No feature declares them: add a migration with DROP TABLE (enable the commented \`-- DESTRUCTIVE\` DROP that \`kumiko schema generate\` emitted; see \`kumiko schema status\`).`,
+                `tables no feature declares anymore: ${listingOf(orphaned)}. No feature declares them: add a migration with DROP TABLE (enable the commented \`-- DESTRUCTIVE\` DROP that \`bun kumiko-schema generate\` emitted; see \`bun kumiko-schema status\`).`,
             ]
             : []),
     ];
@@ -66,7 +66,7 @@ async function assertNoLiveRowLevelSecurity(db, knownTables, scope) {
     if (tables.length === 0)
         return;
     throw new InternalError({
-        message: `rowLevelSecurity is "off" but row-level security is still enabled on: ${tables.join(", ")}. Without a tenant scope every statement would see zero rows. Run \`kumiko schema generate\` with rowLevelSecurity off to produce the DISABLE ROW LEVEL SECURITY migration and apply it.`,
+        message: `rowLevelSecurity is "off" but row-level security is still enabled on: ${tables.join(", ")}. Without a tenant scope every statement would see zero rows. Run \`bun kumiko-schema generate\` with rowLevelSecurity off to produce the DISABLE ROW LEVEL SECURITY migration and apply it.`,
     });
 }
 // Table state only, no role check: the role is a runtime property of the boot connection, so tools

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/migrations/kumiko-drift.js

@@ -125,11 +125,11 @@ export function formatKumikoDriftReport(report) {
     // restored by apply.
     lines.push("");
     if (report.pending.length > 0) {
-        lines.push("Run 'kumiko schema apply' to apply the pending migration(s).");
+        lines.push("Run 'bun kumiko-schema apply' to apply the pending migration(s).");
     }
     if (report.checksumMismatches.length > 0) {
         lines.push("Revert the edited migration file(s) to their applied content, or hand-correct");
-        lines.push("the checksum in _kumiko_migrations — 'kumiko schema apply' cannot resolve a");
+        lines.push("the checksum in _kumiko_migrations — 'bun kumiko-schema apply' cannot resolve a");
         lines.push("checksum mismatch.");
     }
     if (report.missingTables.length > 0 && report.pending.length === 0) {
@@ -138,8 +138,8 @@ export function formatKumikoDriftReport(report) {
     }
     if (report.missingColumns.length > 0) {
         lines.push("Missing column(s) — the live table predates a richer snapshot (e.g. a");
-        lines.push("ride-along column the generator now emits). Run 'kumiko schema generate' to");
-        lines.push("produce an ALTER-TABLE migration for the new column(s), then 'kumiko schema apply'.");
+        lines.push("ride-along column the generator now emits). Run 'bun kumiko-schema generate' to");
+        lines.push("produce an ALTER-TABLE migration for the new column(s), then 'bun kumiko-schema apply'.");
     }
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.390.1",
+  "version": "0.391.1",
   "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.1",
+    "@cosmicdrift/kumiko-types": "0.391.1",
     "bullmq": "^5.76.7",
     "hono": "^4.13.1",
     "i18next": "^26.1.0",
@@ -221,7 +221,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.390.1",
+    "@cosmicdrift/kumiko-testing": "0.391.1",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.2",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.391.1",
+    "type": "fix",
+    "title": "Boot errors name the real schema command",
+    "detail": "The drift report and the row-level-security boot check recommended `kumiko schema apply` and `kumiko schema generate`. Apps run the CLI as `bun kumiko-schema <subcommand>`, so the hints now say that."
+  },
+  {
+    "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",