@cosmicdrift/kumiko-framework 0.369.0 → 0.371.0

package/dist/engine/boot-validator/handler-field-references.d.ts

@@ -1,2 +1,2 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateHandlerFieldReferences(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/i18n-keys.d.ts

@@ -1,2 +1,2 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/index.d.ts

@@ -1,10 +1,10 @@
-import type { EnvelopeCipher } from "../../secrets/envelope-cipher.js";
-import type { FeatureDefinition } from "../types/index.js";
-export { type CardMetaOverflow, collectCardMetaOverflow } from "./card-meta-overflow.js";
-export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
-export { collectWriteHandlerQns } from "./nav.js";
-export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline.js";
-export { MAX_TRANSFER_DEPTH } from "./transfer-graph.js";
+import type { EnvelopeCipher } from "../../secrets/envelope-cipher.ts";
+import type { FeatureDefinition } from "../types/index.ts";
+export { type CardMetaOverflow, collectCardMetaOverflow } from "./card-meta-overflow.ts";
+export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.ts";
+export { collectWriteHandlerQns } from "./nav.ts";
+export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline.ts";
+export { MAX_TRANSFER_DEPTH } from "./transfer-graph.ts";
 export type ValidateBootOptions = {
     /** Warn when an access role is used by exactly one handler/config-key/
      *  field across the whole boot scan — often a typo, but also the normal

package/dist/engine/boot-validator/nav.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types/index.js";
+import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types/index.ts";
 export declare function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string>;
 export declare function collectNavQns(features: readonly FeatureDefinition[]): Map<string, NavDefinition & {
     readonly featureName: string;

package/dist/engine/boot-validator/ownership.d.ts

@@ -1,5 +1,5 @@
-import { type OwnershipMap, type WhereRule } from "../ownership.js";
-import type { ClaimKeyDefinition, FeatureDefinition } from "../types/index.js";
+import { type OwnershipMap, type WhereRule } from "../ownership.ts";
+import type { ClaimKeyDefinition, FeatureDefinition } from "../types/index.ts";
 export type WhereRuleProbe = {
     readonly table: unknown;
     readonly tableName: string;

package/dist/engine/boot-validator/parent-ref.d.ts

@@ -1,3 +1,3 @@
-import type { EntityDefinition, FeatureDefinition } from "../types/index.js";
+import type { EntityDefinition, FeatureDefinition } from "../types/index.ts";
 export declare function findEntity(featureMap: ReadonlyMap<string, FeatureDefinition>, entityName: string): EntityDefinition | undefined;
 export declare function validateParentRefs(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/pii-retention.d.ts

@@ -1,4 +1,4 @@
-import type { EntityDefinition } from "../types/fields.js";
-import type { FeatureDefinition } from "../types/index.js";
+import type { EntityDefinition } from "../types/fields.ts";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function entityHasAnonymizableSubjectField(fields: EntityDefinition["fields"]): boolean;
 export declare function validatePiiAndRetention(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/projection-list-screens.d.ts

@@ -1,4 +1,4 @@
-import { type FeatureDefinition, type QueryHandlerDef } from "../types/index.js";
+import { type FeatureDefinition, type QueryHandlerDef } from "../types/index.ts";
 export declare function buildQueryHandlerMap(features: readonly FeatureDefinition[]): ReadonlyMap<string, QueryHandlerDef>;
 export declare function validateProjectionListScreens(features: readonly FeatureDefinition[]): void;
 export declare function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/query-output-columns.d.ts

@@ -1,2 +1,2 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateQueryOutputColumns(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/query-refs.d.ts

@@ -1,3 +1,3 @@
-import type { FeatureDefinition, QueryHandlerDef } from "../types/index.js";
+import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
 export declare function checkQueryRef(queryHandlers: ReadonlyMap<string, QueryHandlerDef>, query: string, buildPrefix: () => string): void;
 export declare function validateQueryRefs(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/record-owned.d.ts

@@ -1,2 +1,2 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateRecordOwnedSubjects(feature: FeatureDefinition): void;

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

@@ -1,6 +1,6 @@
 import type { IconKey } from "@cosmicdrift/kumiko-types/nav-icon";
-import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.js";
-import type { ActionFormScreenDefinition, DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.js";
+import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.ts";
+import type { ActionFormScreenDefinition, DashboardCustomPanel, DashboardScreenPanel, RelatedListToolbarAction, RowAction, RowFieldExtractor, ScreenDefinition, SecretMintScreenDefinition, ToolbarAction } from "../types/screen.ts";
 export declare function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[];
 export declare function readsNavigateParamsAsFormPrefill(target: ScreenDefinition, explicitEntityId: string | undefined, sourceScreenEntity: string | undefined): boolean;
 export declare function validateActionHasIcon(featureName: string, screenId: string, screenType: "projectionDetail" | "entityEdit" | "entityList" | "projectionList", context: string, action: {

package/dist/engine/boot-validator/security-baseline.d.ts

@@ -1,3 +1,3 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare const SECURITY_BASELINE_FEATURE_NAMES: readonly ["sessions", "crypto-shredding", "rate-limiting", "audit"];
 export declare function warnOnMissingSecurityBaseline(features: readonly FeatureDefinition[], nodeEnv?: string | undefined): void;

package/dist/engine/boot-validator/selector-owner-panels.d.ts

@@ -1,2 +1,2 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function validateExtensionSelectorPanels(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/transfer-graph.d.ts

@@ -1,4 +1,4 @@
-import { MAX_TRANSFER_DEPTH } from "../transfer-adjacency.js";
-import type { FeatureDefinition } from "../types/index.js";
+import { MAX_TRANSFER_DEPTH } from "../transfer-adjacency.ts";
+import type { FeatureDefinition } from "../types/index.ts";
 export { MAX_TRANSFER_DEPTH };
 export declare function validateTransferGraph(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/url-prefill-fields.d.ts

@@ -1,3 +1,3 @@
-import type { FeatureDefinition } from "../types/index.js";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function collectUrlPrefillFieldsByScreenQn(features: readonly FeatureDefinition[]): Map<string, Set<string>>;
 export declare function validateSubmitPrefilledHiddenFields(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/workspaces.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types/index.js";
+import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types/index.ts";
 export declare function collectWorkspaceQns(features: readonly FeatureDefinition[]): Map<string, WorkspaceDefinition & {
     readonly featureName: string;
 }>;

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

@@ -1 +1 @@
-export { type CardMetaOverflow, collectCardMetaOverflow, collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, type ValidateBootOptions, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator/index.js";
+export { type CardMetaOverflow, collectCardMetaOverflow, collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, type ValidateBootOptions, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator/index.ts";

package/dist/engine/bridge-stub.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerContext, SessionUser } from "./types/index.js";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
 export declare function bridgeStub(opts?: {
     readonly user?: SessionUser;
 }): Pick<HandlerContext, "query" | "queryAs" | "write" | "writeAs" | "appendEvent" | "unsafeAppendEvent" | "tryAppendEvent" | "fetchForWriting" | "loadAggregate" | "archiveStream" | "restoreStream" | "isStreamArchived" | "snapshotAggregate" | "loadAggregateWithSnapshot" | "queryProjection" | "resolveAuthClaims" | "resolveActiveMembership" | "queryAsMember" | "hasFeature" | "metrics" | "metricsFor" | "tracer" | "tz" | "locale" | "user">;

package/dist/engine/build-app-schema.d.ts

@@ -1,5 +1,5 @@
-import type { AppSchema } from "../ui-types/index.js";
-import type { Registry } from "./types/feature.js";
+import type { AppSchema } from "../ui-types/index.ts";
+import type { Registry } from "./types/feature.ts";
 export type BuildAppSchemaOptions = {
     /** Dev-server authoring hints (Settings-Hub placement). Default off — only
      *  `createKumikoServer` opts in; prod boot + unit tests stay silent. */

package/dist/engine/build-config-feature-schema.d.ts

@@ -1,8 +1,8 @@
-import type { WorkspaceSchema } from "../ui-types/index.js";
-import type { TranslationKeys } from "./types/config.js";
-import type { Registry } from "./types/feature.js";
-import type { NavDefinition } from "./types/nav.js";
-import type { ScreenDefinition } from "./types/screen.js";
+import type { WorkspaceSchema } from "../ui-types/index.ts";
+import type { TranslationKeys } from "./types/config.ts";
+import type { Registry } from "./types/feature.ts";
+import type { NavDefinition } from "./types/nav.ts";
+import type { ScreenDefinition } from "./types/screen.ts";
 export declare const SETTINGS_HUB_FEATURE = "config";
 export declare const SETTINGS_HUB_WORKSPACE = "settings";
 export type ConfigFeatureSchema = {

package/dist/engine/build-target.d.ts

@@ -1,5 +1,5 @@
-import type { TargetRef } from "./types/target-ref.js";
-import type { TreeActionDef } from "./types/tree-node.js";
+import type { TargetRef } from "./types/target-ref.ts";
+import type { TreeActionDef } from "./types/tree-node.ts";
 type FeatureWithTreeActions<TActions extends Record<string, TreeActionDef>> = {
     readonly id: string;
     readonly treeActions: TActions;

package/dist/engine/changeset-changes.d.ts

@@ -1,4 +1,4 @@
-import { type ChangelogType } from "./feature-changelog.js";
+import { type ChangelogType } from "./feature-changelog.ts";
 export type PendingChange = {
     readonly feature: string;
     readonly type: ChangelogType;

package/dist/engine/codemod/index.d.ts

@@ -1,2 +1,2 @@
-export type { CodemodOptions, CodemodReport, CodemodResult, FileAnalysis, ParsedHandlerInfo, } from "./pipeline-codemod.js";
-export { analyzeFile, analyzeHandlerArrow, convertFile, generatePerformBlock, runCodemod, scanForCandidates, } from "./pipeline-codemod.js";
+export type { CodemodOptions, CodemodReport, CodemodResult, FileAnalysis, ParsedHandlerInfo, } from "./pipeline-codemod.ts";
+export { analyzeFile, analyzeHandlerArrow, convertFile, generatePerformBlock, runCodemod, scanForCandidates, } from "./pipeline-codemod.ts";

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

@@ -1,4 +1,4 @@
-import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValidateFn, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.js";
+import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValidateFn, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.ts";
 export declare function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
 export declare const access: {
     readonly all: readonly string[];

package/dist/engine/constants.d.ts

@@ -1,7 +1,7 @@
 import type { ConcurrencyMode } from "@cosmicdrift/kumiko-types/concurrency-mode";
 import type { ConfigScope } from "@cosmicdrift/kumiko-types/config-scope";
 import type { OnDeleteStrategy as OnDeleteStrategyType } from "@cosmicdrift/kumiko-types/relations";
-import type { TenantId } from "./types/identifiers.js";
+import type { TenantId } from "./types/identifiers.ts";
 export declare const SystemHookNames: {
     readonly cascadeDelete: "system:hook:cascade-delete";
 };

package/dist/engine/create-app.d.ts

@@ -1,5 +1,5 @@
-import { type ValidateBootOptions } from "./boot-validator.js";
-import type { FeatureDefinition, Registry } from "./types/index.js";
+import { type ValidateBootOptions } from "./boot-validator.ts";
+import type { FeatureDefinition, Registry } from "./types/index.ts";
 export type AppConfig = {
     roles: readonly string[];
     features: readonly FeatureDefinition[];

package/dist/engine/cross-tenant.d.ts

@@ -1,4 +1,4 @@
-import { AccessDeniedError } from "../errors/index.js";
-import type { SessionUser } from "./types/index.js";
+import { AccessDeniedError } from "../errors/index.ts";
+import type { SessionUser } from "./types/index.ts";
 export declare function mayOverrideTenant(user: SessionUser): boolean;
 export declare function tenantOverrideDenied(user: SessionUser, parsedPayload: unknown): AccessDeniedError | undefined;

package/dist/engine/dedupe-features.d.ts

@@ -1,2 +1,2 @@
-import type { FeatureDefinition } from "./types/index.js";
+import type { FeatureDefinition } from "./types/index.ts";
 export declare function dedupeFeatures(features: readonly FeatureDefinition[]): FeatureDefinition[];

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

@@ -1,4 +1,4 @@
-import type { FeatureDefinition, FeatureRegistrar } from "./types/index.js";
+import type { FeatureDefinition, FeatureRegistrar } from "./types/index.ts";
 export type DefineFeatureSettings = {
     readonly dedupeOptions?: Readonly<Record<string, unknown>>;
 };

package/dist/engine/define-feature.js

@@ -2,7 +2,7 @@ import { createInitialFeatureBuilderState } from "./feature-builder-state.js";
 import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs.js";
 import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
 import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
-import { isObjectArgument, throwPositionalFormRemoved, unwrapArrayForm } from "./object-form.js";
+import { isObjectArgument, throwObjectArgumentRequired, unwrapArrayForm } from "./object-form.js";
 // `TExports` lets the setup callback hand back a typed object that
 // downstream features can import (e.g. `tenantFeature.exports.config`). The
 // runtime always packs whatever setup returns into `featureDef.exports` —
@@ -49,7 +49,7 @@ export function defineFeature(name, setup, settings) {
         requires: (() => {
             const fn = (...args) => {
                 if (!args.every(isObjectArgument))
-                    throwPositionalFormRemoved(name, "requires");
+                    throwObjectArgumentRequired(name, "requires");
                 state.requires.push(...resolveFeatureNamesArgs(args));
             };
             fn.projection = (tableName) => {

package/dist/engine/define-handler.d.ts

@@ -1,9 +1,9 @@
 import type { CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
 import type { ZodType } from "zod";
-import type { ContainsSecret } from "../secrets/types.js";
-import type { QueryHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput } from "./types/define-handler.js";
-import type { KumikoEventTypeMap } from "./types/index.js";
-export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./types/define-handler.js";
+import type { ContainsSecret } from "../secrets/types.ts";
+import type { QueryHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput } from "./types/define-handler.ts";
+import type { KumikoEventTypeMap } from "./types/index.ts";
+export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./types/define-handler.ts";
 export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined>(def: WriteHandlerInput<TName, TSchema, TData, TMap, TPrepared>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
     secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
 ] : []): WriteHandlerDefinition<TName, TSchema, TData, TMap, TPrepared>;

package/dist/engine/define-step.d.ts

@@ -1,4 +1,4 @@
-import type { StepDef, StepKind } from "./types/step.js";
+import type { StepDef, StepKind } from "./types/step.ts";
 export declare function defineStep<TArgs, TResult>(def: StepDef<TArgs, TResult>): StepDef<TArgs, TResult>;
 export declare function getStep(kind: StepKind): StepDef | undefined;
 export declare function listStepKinds(): readonly StepKind[];

package/dist/engine/define-workflow.d.ts

@@ -1,5 +1,5 @@
-import type { WriteEvent } from "./types/handlers.js";
-import type { AwaitedEventType, PipelineDef } from "./types/step.js";
+import type { WriteEvent } from "./types/handlers.ts";
+import type { AwaitedEventType, PipelineDef } from "./types/step.ts";
 /**
  * Trigger configuration for a workflow. Determines what starts a run.
  */

package/dist/engine/effective-features.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureDefinition, Registry } from "./types/index.js";
+import type { FeatureDefinition, Registry } from "./types/index.ts";
 export type ToggleReader = (featureName: string) => boolean | undefined;
 export declare function isToggleableFeature(feature: FeatureDefinition): feature is FeatureDefinition & {
     toggleableDefault: boolean;

package/dist/engine/embedded-derived.d.ts

@@ -1,4 +1,4 @@
-import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types/index.js";
+import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types/index.ts";
 /** Computes a derived cell from its source values. Missing/non-numeric
  *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every

package/dist/engine/entity-handlers.d.ts

@@ -1,9 +1,10 @@
 import * as z from "zod";
-import { type EventStoreExecutor } from "../db/event-store-executor.js";
-import { type EntityTable } from "../db/table-builder.js";
-import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.js";
-import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.js";
-export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.js";
+import { type EventStoreExecutor } from "../db/event-store-executor.ts";
+import { type EntityTable } from "../db/table-builder.ts";
+import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.ts";
+import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.ts";
+export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.ts";
+export declare function assertEscapeHatchAccessIsSystemAdminOnly(name: string, kind: "write" | "query", access: AccessRule): void;
 export declare const MAX_LIST_LIMIT = 200;
 export declare const entityListSchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;

package/dist/engine/entity-handlers.js

@@ -66,11 +66,14 @@ function resolveCrossTenantReason(name, options, kind) {
     const placeholderProblem = codemodPlaceholderReasonProblem(options.escapeHatch.reason);
     if (placeholderProblem !== undefined)
         throw new Error(`"${name}": ${placeholderProblem}`);
-    if (!isSystemAdminOnly(options.access)) {
-        throw new Error(`"${name}": a ${kind} handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
-    }
+    assertEscapeHatchAccessIsSystemAdminOnly(name, kind, options.access);
     return options.escapeHatch.reason;
 }
+export function assertEscapeHatchAccessIsSystemAdminOnly(name, kind, access) {
+    if (!isSystemAdminOnly(access)) {
+        throw new Error(`"${name}": a ${kind} handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(access)}.`);
+    }
+}
 // Upper bound on entity-list `limit`: unbounded/fractional values ran
 // straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
 // read.ts), letting a client demand a full-table materialisation or trip a

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

@@ -0,0 +1,15 @@
+import { type ZodType } from "zod";
+import type { EventDef, EventPiiStance, QualifiedEventName } from "./types/index.ts";
+export type CreateEventDefOptions<TFeature extends string, TInner extends string, TPayload> = {
+    readonly feature: TFeature;
+    readonly name: TInner;
+    readonly schema: ZodType<TPayload>;
+    readonly version?: number;
+    readonly piiFields: EventPiiStance;
+};
+/**
+ * The EventDef that `r.defineEvent` returns, built outside a feature's setup
+ * callback, so a module can hand the definition to `emitEvent` without the
+ * feature instance. Registration still goes through `r.defineEvent`.
+ */
+export declare function createEventDef<const TFeature extends string, const TInner extends string, TPayload>(options: CreateEventDefOptions<TFeature, TInner, TPayload>): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;

package/dist/engine/event-def.js

@@ -0,0 +1,123 @@
+import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
+import { ZodObject } from "zod";
+import { qn, toKebab } from "./qualified-name.js";
+// A payload field that still holds null/undefined after parsing — the case
+// where an event-PII owner field yields no subject at append time (fw#2776).
+// A `.default(...)` accepts undefined but parses to a value, so it is not
+// absentable.
+function isAbsentable(field) {
+    return [null, undefined].some((candidate) => {
+        const parsed = field.safeParse(candidate);
+        return parsed.success && (parsed.data === null || parsed.data === undefined);
+    });
+}
+const NON_STRING_SCHEMA_TYPES = new Set([
+    "number",
+    "int",
+    "boolean",
+    "bigint",
+    "date",
+    "object",
+    "array",
+]);
+// An owner id is resolved through "non-empty string or absent" at append time,
+// so a schema that can never yield a string would make every append throw in
+// prod. Wrappers (optional/nullable/default/...) are looked through.
+function neverYieldsString(field) {
+    let current = field;
+    for (;;) {
+        const def = current._zod.def;
+        if (def.innerType === undefined)
+            return NON_STRING_SCHEMA_TYPES.has(def.type);
+        current = def.innerType;
+    }
+}
+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" | "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: "self" under the event's own record key, whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
+    }
+}
+// piiFields misconfiguration is a boot-time error, not a silent
+// plaintext leak: both the pii field and its owner field must exist
+// on the payload schema (checkable when the schema is a ZodObject).
+function validateEventPiiFields(featureName, eventName, schema, piiFields) {
+    const shape = schema instanceof ZodObject ? schema.shape : undefined;
+    for (const [field, spec] of Object.entries(piiFields)) {
+        const normalized = normalizeEventPiiSubject(spec);
+        // Only the user form names an owner field — tenant/self subjects come
+        // from the write-time envelope (tenantId / aggregateType+aggregateId),
+        // so there is no owner-field existence or self-reference check for them.
+        if (normalized.kind !== "user") {
+            if (shape && !(field in shape)) {
+                throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields references "${field}" which is not a field of the payload schema.`);
+            }
+            continue;
+        }
+        if (field === normalized.ownerField) {
+            throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as the owner field — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`);
+        }
+        if (normalized.ownerField === "id") {
+            throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" uses owner field "id" — on entities \`of: "id"\` means record-owned, but on events it would encrypt under a phantom user key that a forget never reaches. Use \`personal: "self"\` for a record-owned event field.`);
+        }
+        for (const required of [field, normalized.ownerField]) {
+            if (shape && !(required in shape)) {
+                throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`);
+            }
+        }
+        const owner = shape?.[normalized.ownerField];
+        if (normalized.whenAbsent === undefined && owner !== undefined) {
+            assertOwnerFieldYieldsPresentString({
+                featureName,
+                eventName,
+                field,
+                ownerField: normalized.ownerField,
+                owner,
+            });
+        }
+    }
+}
+/**
+ * The EventDef that `r.defineEvent` returns, built outside a feature's setup
+ * callback, so a module can hand the definition to `emitEvent` without the
+ * feature instance. Registration still goes through `r.defineEvent`.
+ */
+export function createEventDef(options) {
+    const { feature, name: eventName, schema } = options;
+    // Fail-closed PII stance gate (fw#2558) — runs before anything else so
+    // an untyped JS consumer (no compiler to stop it) still can't register
+    // an event without declaring whether its payload carries personal data.
+    const missingStanceError = () => new Error(`[Feature ${feature}] defineEvent("${eventName}") must declare an explicit PII stance. Pass { piiFields: { <payloadField>: { personal: { of: "<userIdField>" } } } } for payload fields owned by a user (or { personal: "tenant" } / { personal: "self" } for tenant- or record-scoped subjects), or { piiFields: "none" } when the payload holds none.`);
+    if (options.piiFields === undefined)
+        throw missingStanceError();
+    const piiFields = options.piiFields;
+    // @cast-boundary runtime-guard — an untyped JS caller can hand
+    // anything through `piiFields` (including null), so re-check the
+    // shape before trusting it as EventPiiStance: `typeof null === "object"`
+    // would otherwise pass through to Object.keys(null) below and throw a
+    // raw TypeError instead of this guidance message.
+    if (piiFields !== "none" && (typeof piiFields !== "object" || piiFields === null)) {
+        throw missingStanceError();
+    }
+    if (piiFields !== "none" && Object.keys(piiFields).length === 0) {
+        throw new Error(`[Feature ${feature}] defineEvent("${eventName}"): piiFields: {} is not a stance — use piiFields: "none" to declare the payload holds no personal data.`);
+    }
+    if (piiFields !== "none")
+        validateEventPiiFields(feature, eventName, schema, piiFields);
+    const version = options.version ?? 1;
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`[Feature ${feature}] defineEvent("${eventName}"): version must be a positive integer, got ${String(version)}`);
+    }
+    // @cast-boundary engine-bridge — runtime-string mirrors the
+    // template-literal-type via QualifiedEventName + toKebab. Both
+    // sides are tested (CamelToKebab type-tests + scan-events kebab
+    // tests), so the cast is a contract, not a typing-loss.
+    const qualified = qn(toKebab(feature), "event", toKebab(eventName));
+    return { name: qualified, schema, version, piiFields };
+}

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

@@ -1,4 +1,4 @@
-import type { AppendEventArgs, EventDef, HandlerContext } from "./types/handlers.js";
+import type { AppendEventArgs, EventDef, HandlerContext } from "./types/handlers.ts";
 export type EmitCtx = Pick<HandlerContext, "unsafeAppendEvent">;
 export declare function emitEvent<TPayload>(ctx: EmitCtx, eventDef: EventDef<TPayload>, args: {
     readonly aggregateId: string;

package/dist/engine/extension-names.d.ts

@@ -1,12 +1,12 @@
 import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
-import type { OverlayResolverPlugin } from "../derivatives/derivatives-context.js";
-import type { FileProviderPlugin } from "../files/provider-resolver.js";
-import type { PrincipalStatusPlugin, TenantLifecycleStatusPlugin } from "./active-membership.js";
-import type { TenantDataExtensionHooks } from "./extensions/tenant-data.js";
-import type { TenantResourceExtensionHooks } from "./extensions/tenant-resource.js";
-import type { UserDataExtensionOptions } from "./extensions/user-data.js";
-import type { AssignableFromRole } from "./role-assignment.js";
-import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension.js";
+import type { OverlayResolverPlugin } from "../derivatives/derivatives-context.ts";
+import type { FileProviderPlugin } from "../files/provider-resolver.ts";
+import type { PrincipalStatusPlugin, TenantLifecycleStatusPlugin } from "./active-membership.ts";
+import type { TenantDataExtensionHooks } from "./extensions/tenant-data.ts";
+import type { TenantResourceExtensionHooks } from "./extensions/tenant-resource.ts";
+import type { UserDataExtensionOptions } from "./extensions/user-data.ts";
+import type { AssignableFromRole } from "./role-assignment.ts";
+import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension.ts";
 /**
  * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
  *

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

@@ -1,5 +1,5 @@
-import type { Registry } from "./types/feature.js";
-import type { RegistrarExtensionRegistration } from "./types/index.js";
+import type { Registry } from "./types/feature.ts";
+import type { RegistrarExtensionRegistration } from "./types/index.ts";
 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[];

package/dist/engine/extensions/escape-hatch-usage.d.ts

@@ -1,2 +1,2 @@
-import type { RegistrarExtensionRegistration } from "../types/config.js";
+import type { RegistrarExtensionRegistration } from "../types/config.ts";
 export declare function extensionUsageEscapeHatchReason(usage: Pick<RegistrarExtensionRegistration, "options">): string | undefined;

package/dist/engine/extensions/storage-provider.d.ts

@@ -1,4 +1,4 @@
-import type { TenantResourceDestroyHook, TenantResourceExtensionHooks, TenantResourceHookCtx } from "./tenant-resource.js";
+import type { TenantResourceDestroyHook, TenantResourceExtensionHooks, TenantResourceHookCtx } from "./tenant-resource.ts";
 export type StorageProviderHookCtx = TenantResourceHookCtx;
 export type StorageProviderDestroyTenantHook = TenantResourceDestroyHook;
 export type StorageProviderExtensionHooks = TenantResourceExtensionHooks;

package/dist/engine/extensions/tenant-data.d.ts

@@ -1,7 +1,7 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
-import type { TenantDb } from "../../db/tenant-db.js";
-import type { Registry, TenantId } from "../types/index.js";
-import type { TenantDestroyHookResult } from "./tenant-resource.js";
+import type { TenantDb } from "../../db/tenant-db.ts";
+import type { Registry, TenantId } from "../types/index.ts";
+import type { TenantDestroyHookResult } from "./tenant-resource.ts";
 export interface TenantDataHookCtx {
     readonly db: TenantDb;
     readonly registry: Registry;

package/dist/engine/extensions/tenant-resource.d.ts

@@ -1,6 +1,6 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
-import type { DbRunner } from "../../db/connection.js";
-import type { TenantId } from "../types/index.js";
+import type { DbRunner } from "../../db/connection.ts";
+import type { TenantId } from "../types/index.ts";
 export type TenantDestroyHookResult = {
     readonly done: true;
     readonly processed?: number;

package/dist/engine/extensions/user-data.d.ts

@@ -1,5 +1,5 @@
-import type { TenantDb } from "../../db/tenant-db.js";
-import type { Registry, TenantId } from "../types/index.js";
+import type { TenantDb } from "../../db/tenant-db.ts";
+import type { Registry, TenantId } from "../types/index.ts";
 type UserId = string;
 /**
  * Strategie für den Forget-Pfad pro Entity:

package/dist/engine/factories.d.ts

@@ -1,5 +1,5 @@
 import type { EntityTenancy } from "@cosmicdrift/kumiko-types/tenancy-brand";
-import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TextFieldDef, TimestampFieldDef, TzFieldDef } from "./types/index.js";
+import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TextFieldDef, TimestampFieldDef, TzFieldDef } from "./types/index.ts";
 export declare function createTextField<R extends true | false = false>(overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotations & {
     required?: R;
 }): TextFieldDef & {

package/dist/engine/feature-ast/extractors/ai-steps.d.ts

@@ -1,6 +1,6 @@
 import type { CallExpression, SourceFile } from "ts-morph";
-import type { AiClassifyPattern, AiExtractPattern, AiGeneratePattern } from "../patterns.js";
-import { type ExtractOutput } from "./shared.js";
+import type { AiClassifyPattern, AiExtractPattern, AiGeneratePattern } from "../patterns.ts";
+import { type ExtractOutput } from "./shared.ts";
 export declare function extractAiGenerate(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AiGeneratePattern>;
 export declare function extractAiExtract(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AiExtractPattern>;
 export declare function extractAiClassify(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AiClassifyPattern>;

package/dist/engine/feature-ast/extractors/events.d.ts

@@ -1,5 +1,5 @@
 import type { CallExpression, SourceFile } from "ts-morph";
-import type { DefineEventPattern, NotificationPattern } from "../patterns.js";
-import { type ExtractOutput } from "./shared.js";
+import type { DefineEventPattern, NotificationPattern } from "../patterns.ts";
+import { type ExtractOutput } from "./shared.ts";
 export declare function extractDefineEvent(call: CallExpression, sourceFile: SourceFile): ExtractOutput<DefineEventPattern>;
 export declare function extractNotification(call: CallExpression, sourceFile: SourceFile): ExtractOutput<NotificationPattern>;