@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

package/dist/engine/build-config-feature-schema.js

@@ -17,9 +17,10 @@
 import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
 import { CONFIG_EDIT_ENTITY, fieldLabelKey } from "../i18n/required-surface-keys.js";
 import { isEncryptedAtRest } from "./config-helpers.js";
-import { EXTENSION_SELECTOR_HINT_KEY, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
+import { EXTENSION_SELECTOR_HINT_KEY, isSelectableInSettings, settingsSelectablePluginIds, } from "./extension-selector-plugins.js";
 import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
 import { isKebabSegment, toKebab } from "./qualified-name.js";
+import { isFieldsEditSection, sectionFieldSpecs } from "./screen-helpers.js";
 import { isOpenToAllGranted } from "./types/handlers.js";
 // Namespace, unter dem buildAppSchema die generierten Screens/Navs einhängt
 // (find-or-create FeatureSchema). MUSS gleich CONFIG_FEATURE aus dem config
@@ -45,7 +46,7 @@ const PROVIDER_PANEL_TITLE_ENTRY = {
     es: "Proveedor",
 };
 const PROVIDER_SECTION_TITLE_KEY = "config.settings.provider";
-const SAVE_PROVIDER_LABEL_KEY = "config.settings.saveProvider";
+const SECRETS_SECTION_DESCRIPTION_KEY = "config.secrets.description";
 const audienceNavShortId = (scope) => `audience-${scope}`;
 // Generated post-boot, never via r.nav() — the boot validator exempts exactly these QNs (an app references one to place the settings group inline).
 export const SETTINGS_HUB_AUDIENCE_NAV_QNS = SCOPES_BROAD_TO_DEEP.map((scope) => `${SETTINGS_HUB_FEATURE}:nav:${audienceNavShortId(scope)}`);
@@ -73,25 +74,43 @@ const NO_SELECTOR_GATING = {
 };
 // Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
 // (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
+// Merged per locale: a locale feature (localeDe) declares the same key with only its
+// own language, and mounted first it must not drop the owning feature's en text.
 function collectDeclaredTranslations(registry) {
     const declared = new Map();
     for (const f of registry.features.values()) {
         for (const [key, values] of Object.entries(f.translations ?? {})) {
-            if (!declared.has(key))
-                declared.set(key, values);
+            declared.set(key, { ...values, ...declared.get(key) });
         }
     }
     return declared;
 }
+// A selector whose plugins are all hidden from settings still renders as a select
+// (with no option), never as a free text field.
 function collectSelectorOptions(registry) {
     const options = new Map();
     for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
-        const pluginIds = selectablePluginIds(registry, extensionName);
-        if (pluginIds.length > 0)
-            options.set(selectorKey, pluginIds);
+        if (registry.getExtensionUsages(extensionName).length === 0)
+            continue;
+        options.set(selectorKey, settingsSelectablePluginIds(registry, extensionName));
     }
     return options;
 }
+// selector key → plugin id → plugin feature, for every selectable plugin, also those
+// without settings of their own (no panel, but still an option with a name).
+function collectSelectorOptionFeatures(registry) {
+    const byKey = new Map();
+    for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+        const featureByPluginId = new Map();
+        for (const usage of registry.getExtensionUsages(extensionName).filter(isSelectableInSettings)) {
+            if (usage.featureName === undefined || featureByPluginId.has(usage.entityName))
+                continue;
+            featureByPluginId.set(usage.entityName, toKebab(usage.featureName));
+        }
+        byKey.set(selectorKey, featureByPluginId);
+    }
+    return byKey;
+}
 function collectVisibleSelectorOwners(registry, visible) {
     const ownerGroupByExtension = new Map();
     const selectorFeatures = new Set();
@@ -141,6 +160,9 @@ function planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
     const secretQns = new Set();
     for (const [extension, ownerGroup] of [...ownerGroupByExtension].sort(([a], [b]) => a.localeCompare(b))) {
         const usages = [...registry.getExtensionUsages(extension)].sort((a, b) => (a.featureName ?? "").localeCompare(b.featureName ?? ""));
+        const selectorQn = registry.getAllExtensionSelectors().get(extension);
+        if (selectorQn === undefined)
+            continue;
         for (const usage of usages) {
             if (usage.featureName === undefined)
                 continue;
@@ -148,11 +170,22 @@ function planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
             if (usageCountByFeature.get(feature) !== 1 || selectorFeatures.has(feature))
                 continue;
             const scopedKeys = visible.filter((v) => v.key.ownerFeature === feature);
-            const secrets = secretsEnabled ? declaredSecrets.filter((s) => s.feature === feature) : [];
+            // The provider form has no per-field access gate, so a secret with its own write
+            // roles stays on the secrets screen, which enforces them.
+            const secrets = secretsEnabled
+                ? declaredSecrets.filter((s) => s.feature === feature && s.def.writeRoles === undefined)
+                : [];
             if (scopedKeys.length === 0 && secrets.length === 0)
                 continue;
             const plugins = pluginsByOwnerGroup.get(ownerGroup) ?? [];
-            plugins.push({ feature, extension, pluginId: usage.entityName, scopedKeys, secrets });
+            plugins.push({
+                feature,
+                extension,
+                selectorQn,
+                pluginId: usage.entityName,
+                scopedKeys,
+                secrets,
+            });
             pluginsByOwnerGroup.set(ownerGroup, plugins);
             pluginFeatures.add(feature);
             for (const s of secrets)
@@ -204,9 +237,6 @@ function buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess)
     }
     return out;
 }
-function pluginTenantScreenId(plugin) {
-    return `${plugin.feature}-tenant`;
-}
 function assertUniquePanelIds(ownerGroup, panels) {
     const seen = new Set();
     for (const panel of panels) {
@@ -218,63 +248,38 @@ function assertUniquePanelIds(ownerGroup, panels) {
     }
     return panels;
 }
-// Plugin screens keep their `${F}-tenant` ids so consumer title keys stay valid;
-// they are dormant because only this dashboard embeds them.
+// One form for the provider and the settings of every provider: a single save writes
+// all of it, so switching sections can't drop typed input. Each plugin's fields are
+// shown only while its provider is picked in the form; hidden fields are not saved.
 function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins, ownerPanels, hub, secretsAccess) {
     const selectionScreenId = `${ownerGroup}-tenant-selection`;
-    const selectionScreen = {
-        ...buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub, {
-            description: EXTENSION_SELECTOR_HINT_KEY,
-            sectionTitle: PROVIDER_SECTION_TITLE_KEY,
-            submitLabel: SAVE_PROVIDER_LABEL_KEY,
-        }),
-        dormant: true,
-    };
-    const screens = [selectionScreen];
-    const configPanels = [];
-    const secretsPanels = [];
+    const form = new ProviderFormBuilder(selectionScreenId, buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub, {
+        description: EXTENSION_SELECTOR_HINT_KEY,
+        sectionTitle: PROVIDER_SECTION_TITLE_KEY,
+    }));
     const accessRules = [ownerAccess];
     const translations = {};
     translations[`screen:${selectionScreenId}.title`] = PROVIDER_PANEL_TITLE_ENTRY;
-    Object.assign(translations, providerOptionTranslations(selectionScreen, plugins, hub));
+    Object.assign(translations, providerOptionTranslations(form.base, hub));
     for (const plugin of plugins) {
-        const visibleWhen = {
-            query: SELECTED_EXTENSIONS_QUERY,
-            field: plugin.extension,
-            eq: plugin.pluginId,
-        };
+        const providerFieldId = form.fieldIdOfConfigKey(plugin.selectorQn);
+        const visible = { field: providerFieldId, eq: plugin.pluginId };
+        let pluginSection;
         if (plugin.scopedKeys.length > 0) {
             const pluginAccess = rolesToAccess(plugin.scopedKeys.flatMap((v) => v.roles));
-            const ordered = sortByMaskOrder(plugin.scopedKeys.map((v) => v.key));
-            screens.push({
-                ...buildScreen(pluginTenantScreenId(plugin), "tenant", plugin.feature, ordered, pluginAccess, hub, { description: null }),
-                dormant: true,
-            });
+            const pluginScreen = buildScreen(`${plugin.feature}-tenant`, "tenant", plugin.feature, sortByMaskOrder(plugin.scopedKeys.map((v) => v.key)), pluginAccess, hub, { description: null, fieldIdOf: qualifiedFieldId });
+            pluginSection = form.addConfigFields(pluginScreen, visible);
             accessRules.push(pluginAccess);
-            configPanels.push({
-                kind: "screen",
-                id: `${plugin.feature}-config`,
-                screen: pluginTenantScreenId(plugin),
-                visibleWhen,
-                chromeless: true,
-            });
         }
         if (plugin.secrets.length > 0) {
-            const secretsScreenId = `${plugin.feature}-tenant-secrets`;
-            const generated = buildSecretsEditScreen(secretsScreenId, plugin.secrets, secretsAccess, hub.declaredTranslationKeys);
-            screens.push({ ...generated.screen, dormant: true });
+            const generated = buildSecretsEditScreen(`${plugin.feature}-tenant-secrets`, plugin.secrets, secretsAccess, hub.declaredTranslationKeys);
+            form.addSecretFields(generated.screen, plugin.feature, visible, pluginSection);
             Object.assign(translations, generated.translations);
             accessRules.push(secretsAccess);
-            secretsPanels.push({
-                kind: "screen",
-                id: `${plugin.feature}-secrets`,
-                screen: secretsScreenId,
-                visibleWhen,
-                chromeless: true,
-            });
         }
     }
     const access = unionAccessRules(accessRules);
+    const selectionScreen = { ...form.build(access), dormant: true };
     const dashboard = {
         id: `${ownerGroup}-tenant`,
         type: "dashboard",
@@ -282,16 +287,136 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
         panels: assertUniquePanelIds(ownerGroup, [
             { kind: "screen", id: "selection", screen: selectionScreenId, chromeless: true },
             ...ownerPanels,
-            ...configPanels,
-            ...secretsPanels,
         ]),
         access,
     };
-    return { screens: [dashboard, ...screens], access, translations };
+    return { screens: [dashboard, selectionScreen], access, translations };
+}
+// A plugin key keeps its feature in the field id: the provider form holds the keys of
+// several features side by side.
+function qualifiedFieldId(k) {
+    return `${k.ownerFeature}-${k.shortKey}`;
+}
+class ProviderFormBuilder {
+    screenId;
+    base;
+    configKeys;
+    secretKeys = {};
+    fields;
+    fieldLabels;
+    fieldDescriptions;
+    requiredFields;
+    sections;
+    constructor(screenId, base) {
+        this.screenId = screenId;
+        this.base = base;
+        this.configKeys = { ...base.configKeys };
+        this.fields = { ...base.fields };
+        this.fieldLabels = { ...base.fieldLabels };
+        this.fieldDescriptions = { ...base.fieldDescriptions };
+        this.requiredFields = [...(base.requiredFields ?? [])];
+        this.sections = base.layout.sections.filter(isFieldsEditSection);
+    }
+    fieldIdOfConfigKey(qn) {
+        const entry = Object.entries(this.base.configKeys).find(([, keyQn]) => keyQn === qn);
+        if (entry === undefined) {
+            throw new Error(`[Settings-Hub] selector key "${qn}" is not on "${this.screenId}".`);
+        }
+        return entry[0];
+    }
+    addConfigFields(pluginScreen, visible) {
+        for (const [id, qn] of Object.entries(pluginScreen.configKeys)) {
+            this.claim(id, qn);
+            this.configKeys[id] = qn;
+            const field = pluginScreen.fields[id];
+            if (field !== undefined)
+                this.fields[id] = field;
+        }
+        Object.assign(this.fieldLabels, pluginScreen.fieldLabels);
+        Object.assign(this.fieldDescriptions, pluginScreen.fieldDescriptions);
+        this.requiredFields.push(...(pluginScreen.requiredFields ?? []));
+        const section = pluginScreen.layout.sections.find(isFieldsEditSection);
+        if (section === undefined)
+            return undefined;
+        const { groups: _groups, ...flatSection } = section;
+        const gated = {
+            ...flatSection,
+            fields: gateFields(sectionFieldSpecs(section), visible),
+        };
+        this.sections.push(gated);
+        return gated;
+    }
+    // A plugin's sign-in data gets its own section when the plugin names one, else it
+    // continues the plugin's settings section.
+    addSecretFields(secretsScreen, feature, visible, pluginSection) {
+        for (const [id, qn] of Object.entries(secretsScreen.secretKeys)) {
+            this.claim(id, qn);
+            this.secretKeys[id] = qn;
+            this.fields[id] = createTextField({
+                personal: false,
+                reason: "system_metadata",
+                writeOnly: true,
+            });
+        }
+        Object.assign(this.fieldLabels, secretsScreen.fieldLabels);
+        Object.assign(this.fieldDescriptions, secretsScreen.fieldHints);
+        this.requiredFields.push(...(secretsScreen.requiredFields ?? []));
+        const secretsTitleKey = `${feature}.settings.secrets`;
+        for (const section of secretsScreen.sections) {
+            // kumiko-lint-ignore section-fields-raw a secretsEdit section is a flat key list without groups
+            const fields = gateFields(section.fields, visible);
+            const ownSection = section.title === secretsTitleKey || pluginSection === undefined;
+            if (ownSection) {
+                this.sections.push({
+                    title: section.title ?? `${feature}.settings`,
+                    description: SECRETS_SECTION_DESCRIPTION_KEY,
+                    fields,
+                });
+                continue;
+            }
+            const index = this.sections.indexOf(pluginSection);
+            this.sections[index] = {
+                ...pluginSection,
+                fields: [...sectionFieldSpecs(pluginSection), ...fields],
+            };
+        }
+    }
+    build(access) {
+        const { fieldDescriptions: _baseDescriptions, requiredFields: _baseRequired, ...base } = this.base;
+        return {
+            ...base,
+            configKeys: this.configKeys,
+            ...(Object.keys(this.secretKeys).length > 0 && { secretKeys: this.secretKeys }),
+            fields: this.fields,
+            fieldLabels: this.fieldLabels,
+            ...(Object.keys(this.fieldDescriptions).length > 0 && {
+                fieldDescriptions: this.fieldDescriptions,
+            }),
+            ...(this.requiredFields.length > 0 && { requiredFields: this.requiredFields }),
+            layout: { ...base.layout, sections: this.sections },
+            access,
+        };
+    }
+    claim(id, qn) {
+        const previous = this.configKeys[id] ?? this.secretKeys[id];
+        if (previous !== undefined) {
+            throw new Error(`[Settings-Hub] "${previous}" and "${qn}" both resolve to field id "${id}" on "${this.screenId}" — rename one key.`);
+        }
+    }
+}
+function gateFields(fields, visible) {
+    return fields.map((spec) => typeof spec === "string" ? { field: spec, visible } : { ...spec, visible });
 }
 // Everything generated for one audience scope: the audience-parent nav, the
 // per-feature configEdit screens+navs, and (tenant-scope only, when secrets
 // are enabled) the secrets screen. Null when nothing is visible at this scope.
+// The secrets set handler also admits the machine role for server-side writes; like the
+// config keys' write roles, that role must not reach a screen or nav access gate.
+function withoutMachineRole(rule) {
+    if (rule === undefined || !("roles" in rule))
+        return rule;
+    return { ...rule, roles: rule.roles.filter((role) => role !== MACHINE_WRITE_ROLE) };
+}
 function buildScopeResult(scope, masked, secretsEnabled, secretsWriteHandler, declaredSecrets, hub, registry) {
     const visible = scopedKeysAt(masked, scope);
     // Secrets attach to the tenant-audience nav regardless of whether any
@@ -300,7 +425,7 @@ function buildScopeResult(scope, masked, secretsEnabled, secretsWriteHandler, de
     if (visible.length === 0 && !includeSecrets)
         return null;
     const configAccess = rolesToAccess(visible.flatMap((v) => v.roles));
-    const secretsAccess = secretsWriteHandler?.access;
+    const secretsAccess = withoutMachineRole(secretsWriteHandler?.access);
     const gating = scope === "tenant"
         ? planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
         : NO_SELECTOR_GATING;
@@ -346,6 +471,7 @@ export function buildConfigFeatureSchema(registry) {
     const hub = {
         declaredTranslationKeys: new Set(translationsByKey.keys()),
         selectorOptions: collectSelectorOptions(registry),
+        selectorOptionFeatures: collectSelectorOptionFeatures(registry),
         translationsByKey,
     };
     const screens = [];
@@ -440,7 +566,12 @@ function buildSecretsEditScreen(screenId, secrets, access, declaredTranslationKe
             if (s.def.writeRoles !== undefined)
                 fieldAccess[fieldId] = { roles: [...s.def.writeRoles] };
         }
-        const titleKey = `${feature}.settings`;
+        // Opt-in `${feature}.settings.secrets`: in a selector dashboard this section sits right
+        // under the plugin's own settings section, which already carries `${feature}.settings`.
+        const secretsTitleKey = `${feature}.settings.secrets`;
+        const titleKey = declaredTranslationKeys.has(secretsTitleKey)
+            ? secretsTitleKey
+            : `${feature}.settings`;
         sections.push({
             ...(declaredTranslationKeys.has(titleKey) && { title: titleKey }),
             fields: fieldIds,
@@ -514,7 +645,8 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
     // feature's group (100% of today's apps — byte-identical output). Only a
     // cross-feature `group` (feature !== ownerFeature) needs the owner prefix,
     // to keep two features sharing a group from clobbering the same shortKey.
-    const fieldId = (k) => k.feature === k.ownerFeature ? k.shortKey : `${k.ownerFeature}-${k.shortKey}`;
+    const fieldId = options.fieldIdOf ??
+        ((k) => (k.feature === k.ownerFeature ? k.shortKey : qualifiedFieldId(k)));
     const seenFieldIds = new Map();
     for (const k of keys) {
         const id = fieldId(k);
@@ -544,7 +676,6 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
         ...(Object.keys(fieldDescriptions).length > 0 && { fieldDescriptions }),
         ...(requiredFields.length > 0 && { requiredFields }),
         ...(screenDescription !== undefined && { description: screenDescription }),
-        ...(options.submitLabel !== undefined && { submitLabel: options.submitLabel }),
         layout: { sections: [section], width: "full", variant: "settings-list" },
         access,
     };
@@ -589,16 +720,17 @@ function buildSettingsSection(feature, scope, fieldIds, hub, options) {
 }
 // Option labels of the provider select: each plugin feature's `<feature>.settings`
 // copy, under the option-label key the configEdit renderer already derives.
-function providerOptionTranslations(selectionScreen, plugins, hub) {
+function providerOptionTranslations(selectionScreen, hub) {
     const out = {};
     for (const [fieldId, qn] of Object.entries(selectionScreen.configKeys)) {
-        if (!hub.selectorOptions.has(qn))
+        const featureByPluginId = hub.selectorOptionFeatures.get(qn);
+        if (featureByPluginId === undefined)
             continue;
-        for (const plugin of plugins) {
-            const label = hub.translationsByKey.get(`${plugin.feature}.settings`);
+        for (const [pluginId, feature] of featureByPluginId) {
+            const label = hub.translationsByKey.get(`${feature}.settings`);
             if (label === undefined)
                 continue;
-            const key = `${fieldLabelKey(SETTINGS_HUB_FEATURE, CONFIG_EDIT_ENTITY, fieldId)}:option:${plugin.pluginId}`;
+            const key = `${fieldLabelKey(SETTINGS_HUB_FEATURE, CONFIG_EDIT_ENTITY, fieldId)}:option:${pluginId}`;
             out[key] = label;
         }
     }

package/dist/engine/event-helpers.d.ts

@@ -1,9 +1,10 @@
-import type { EventDef, HandlerContext } from "./types/handlers.js";
+import type { AppendEventArgs, EventDef, HandlerContext } from "./types/handlers.js";
 export type EmitCtx = Pick<HandlerContext, "unsafeAppendEvent">;
 export declare function emitEvent<TPayload>(ctx: EmitCtx, eventDef: EventDef<TPayload>, args: {
     readonly aggregateId: string;
     readonly aggregateType: string;
     readonly payload: TPayload;
+    readonly headers?: AppendEventArgs["headers"];
 }): Promise<void>;
 export declare function typedPayload<TPayload>(event: {
     readonly type: string;

package/dist/engine/event-helpers.js

@@ -21,6 +21,7 @@ export async function emitEvent(ctx, eventDef, args) {
         aggregateType: args.aggregateType,
         type: eventDef.name,
         payload: args.payload,
+        ...(args.headers !== undefined && { headers: args.headers }),
     };
     await ctx.unsafeAppendEvent(appendArgs);
 }

package/dist/engine/extension-selector-plugins.d.ts

@@ -1,5 +1,8 @@
 import type { Registry } from "./types/feature.js";
+import type { RegistrarExtensionRegistration } from "./types/index.js";
 export declare const SELECTED_EXTENSIONS_QUERY = "config:query:config-value:selected-extensions";
 export declare const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHint";
 export declare function selectablePluginIds(registry: Pick<Registry, "getExtensionUsages">, extensionName: string): string[];
+export declare function isSelectableInSettings(usage: RegistrarExtensionRegistration): boolean;
+export declare function settingsSelectablePluginIds(registry: Pick<Registry, "getExtensionUsages">, extensionName: string): string[];
 export declare function extensionSelectorTargets(registry: Pick<Registry, "getAllExtensionSelectors">): ReadonlyMap<string, string>;

package/dist/engine/extension-selector-plugins.js

@@ -5,6 +5,20 @@ export const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHin
 export function selectablePluginIds(registry, extensionName) {
     return [...new Set(registry.getExtensionUsages(extensionName).map((u) => u.entityName))].sort();
 }
+// A plugin registered with `selectableInSettings: false` (a test inbox) stays a valid
+// stored value for seeds and dev setups, but the generated settings never offer it.
+const SELECTABLE_IN_SETTINGS_OPTION = "selectableInSettings";
+export function isSelectableInSettings(usage) {
+    return usage.options?.[SELECTABLE_IN_SETTINGS_OPTION] !== false;
+}
+export function settingsSelectablePluginIds(registry, extensionName) {
+    return [
+        ...new Set(registry
+            .getExtensionUsages(extensionName)
+            .filter(isSelectableInSettings)
+            .map((u) => u.entityName)),
+    ].sort();
+}
 export function extensionSelectorTargets(registry) {
     const extensionByKey = new Map();
     for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {

package/dist/engine/feature-config-events-jobs.d.ts

@@ -28,6 +28,7 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly renamedFrom?: readonly string[];
         readonly systemOnly?: boolean;
         readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
     }), definition?: {
         readonly trigger?: {
             readonly on: NameOrRef;
@@ -43,6 +44,7 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly renamedFrom?: readonly string[];
         readonly systemOnly?: boolean;
         readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent: <const TInner extends string, TPayload>(eventName: TInner, schema: ZodType<TPayload>, options: {

package/dist/engine/feature-config-events-jobs.js

@@ -40,12 +40,12 @@ function assertOwnerFieldYieldsPresentString(args) {
     const { featureName, eventName, field, ownerField, owner } = args;
     if (neverYieldsString(owner)) {
         throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${ownerField}", whose payload schema is not a string — the subject id must be a non-empty string, so every append would fail. ` +
-            `Use a string owner field, or declare whenAbsent ("tenant" | "plaintext").`);
+            `Use a string owner field, or declare whenAbsent ("tenant" | "self" | "plaintext").`);
     }
     if (isAbsentable(owner)) {
         throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${ownerField}", which the payload schema allows to be null/undefined. ` +
             `Declare what happens then: { personal: { of: "${ownerField}", whenAbsent: "tenant" } } encrypts under the envelope tenant key, ` +
-            `whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
+            `whenAbsent: "self" under the event's own record key, whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
     }
 }
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
@@ -222,6 +222,7 @@ export function buildConfigEventsJobsMethods(state, name) {
                     : {}),
                 ...(resolvedDefinition.systemOnly === true ? { systemOnly: true } : {}),
                 ...(resolvedDefinition.unsubscribe === true ? { unsubscribe: true } : {}),
+                ...(resolvedDefinition.tenantTransport === true ? { tenantTransport: true } : {}),
             };
         },
         translations(def) {

package/dist/engine/index.d.ts

@@ -4,6 +4,7 @@ export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, type PrincipalP
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { type CardMetaOverflow, collectCardMetaOverflow, collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, type ValidateBootOptions, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
+export { bridgeStub } from "./bridge-stub.js";
 export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema.js";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema.js";
 export { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE, } from "./build-config-feature-schema.js";

package/dist/engine/index.js

@@ -5,6 +5,7 @@ export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, TENANT_TEARDOWN
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { collectCardMetaOverflow, collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
+export { bridgeStub } from "./bridge-stub.js";
 export { buildAppSchema } from "./build-app-schema.js";
 export { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE, } from "./build-config-feature-schema.js";
 export { buildTarget } from "./build-target.js";

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

@@ -12,7 +12,7 @@
 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 { unsafePushTables } from "../stack/index.js";
+import { unsafePushTables } from "../db/table-push.js";
 export const esOperationsTable = pgTable("kumiko_es_operations", {
     // Filename without extension serves as ID. Chronologically sortable
     // (date-prefix convention), human-meaningful, no separate hash needed.

package/dist/event-store/admin-api.js

@@ -7,10 +7,10 @@
 // Guard-Script `scripts/guard-admin-api.ts` blockt Aufrufe aus App-Code —
 // Allowlist: samples/*/migration/, scripts/migrations/, die Definition
 // selbst, das Guard-Script selbst.
-import { instantToTimestamptzParam } from "../bun-db/query.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, runAtomicEventWrite } from "../db/queries/event-store.js";
 import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";
+import { instantToTimestamptzParam } from "../db/query.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
 function mapEventUniqueViolation(e, event) {
     if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {

package/dist/event-store/archive.js

@@ -3,7 +3,7 @@ import { instant, table as pgTable, sql, text, uniqueIndex, uuid } from "../db/d
 import { upsertArchivedStream } from "../db/queries/event-store.js";
 import { deleteMany, fetchOne } from "../db/query.js";
 import { tableExists } from "../db/schema-inspection.js";
-import { unsafePushTables } from "../stack/index.js";
+import { unsafePushTables } from "../db/table-push.js";
 // Marten-aligned stream archival. Archived streams become read-only: fresh
 // appendEvent on an archived aggregate throws, and loadAggregate returns
 // an empty slice unless the caller passes { includeArchived: true }.

package/dist/event-store/errors.d.ts

@@ -2,7 +2,8 @@
 export declare class VersionConflictError extends Error {
     readonly aggregateId: string;
     readonly expectedVersion: number;
-    constructor(aggregateId: string, expectedVersion: number);
+    readonly currentVersion: number | undefined;
+    constructor(aggregateId: string, expectedVersion: number, currentVersion?: number);
 }
 export declare class IdempotentAppendConflictError extends Error {
     readonly tenantId: string;

package/dist/event-store/errors.js

@@ -9,8 +9,12 @@
 export class VersionConflictError extends Error {
     aggregateId;
     expectedVersion;
-    constructor(aggregateId, expectedVersion) {
-        super(`Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}`);
+    // Undefined when the conflict surfaced as a bare unique violation with no lookup possible.
+    currentVersion;
+    constructor(aggregateId, expectedVersion, currentVersion) {
+        super(`Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}` +
+            (currentVersion === undefined ? "" : `, stream is at version ${currentVersion}`));
+        this.currentVersion = currentVersion;
         this.name = "VersionConflictError";
         this.aggregateId = aggregateId;
         this.expectedVersion = expectedVersion;

package/dist/event-store/event-store.js

@@ -2,11 +2,10 @@
 import { isPersonalDataGated, UNATTRIBUTED_ORIGIN, } from "@cosmicdrift/kumiko-types/event-store-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
-import { instantToTimestamptzParam } from "../bun-db/query.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
-import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
-import { insertOne, selectMany } from "../db/query.js";
+import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
+import { instantToTimestamptzParam, selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 import { eventsTable } from "./events-schema.js";
@@ -112,21 +111,21 @@ async function assertSeedTimeNotBeforePredecessor(db, event, seedCreatedAt) {
     }
 }
 async function insertFirstEvent(db, event, newVersion, eventVersion, seedCreatedAt) {
-    const row = await insertOne(db, eventsTable, {
+    const row = await insertFirstEventRow(db, {
         aggregateId: event.aggregateId,
         aggregateType: event.aggregateType,
         tenantId: event.tenantId,
-        version: newVersion,
+        newVersion,
         type: event.type,
         eventVersion,
         payload: event.payload,
         metadata: event.metadata,
         createdBy: event.metadata.userId,
-        ...(seedCreatedAt !== undefined && { createdAt: seedCreatedAt }),
+        createdAt: seedCreatedAt && instantToTimestamptzParam(seedCreatedAt),
     });
     if (!row)
-        throw new Error("insertFirstEvent: INSERT RETURNING produced no row");
-    return { id: row.id, createdAt: row.createdAt };
+        throw await versionConflictWithCurrentVersion(db, event);
+    return insertReturnOf(row);
 }
 // Subsequent event — predecessor must exist AND belong to the same tenant.
 // INSERT … SELECT … WHERE EXISTS is awkward in the typed builder, so this
@@ -147,7 +146,10 @@ async function insertSubsequentEvent(db, event, newVersion, eventVersion, seedCr
         createdAt: seedCreatedAt && instantToTimestamptzParam(seedCreatedAt),
     });
     if (!row)
-        throw new VersionConflictError(event.aggregateId, event.expectedVersion);
+        throw await versionConflictWithCurrentVersion(db, event);
+    return insertReturnOf(row);
+}
+function insertReturnOf(row) {
     const createdAt = row.created_at instanceof Date
         ? Temporal.Instant.fromEpochMilliseconds(row.created_at.getTime())
         : Temporal.Instant.from(row.created_at);
@@ -156,6 +158,12 @@ async function insertSubsequentEvent(db, event, newVersion, eventVersion, seedCr
         createdAt,
     };
 }
+// Runs in the still-healthy write transaction: ON CONFLICT DO NOTHING left it
+// unaborted, so the stream version is readable here.
+async function versionConflictWithCurrentVersion(db, event) {
+    const currentVersion = await selectStreamMaxVersion(db, event.aggregateId, event.tenantId);
+    return new VersionConflictError(event.aggregateId, event.expectedVersion, currentVersion);
+}
 function buildStoredEvent(event, newVersion, eventVersion, row) {
     return {
         id: String(row.id),