@cosmicdrift/kumiko-framework 0.389.0 → 0.390.1

package/dist/entrypoint/row-level-security-mode-check.js

@@ -0,0 +1,19 @@
+import { DEFAULT_ROW_LEVEL_SECURITY_MODE, } from "../db/render-rls-ddl.js";
+import { rowLevelSecurityModeOf } from "../db/row-level-security-connection.js";
+import { InternalError } from "../errors/index.js";
+// The mode lives on the connection; the option states what the app config declared.
+// A mismatch means the pools were opened for a different mode than the one the
+// schema was applied for, which silently drops or over-applies tenant isolation.
+export function assertEntrypointRowLevelSecurityMode(context, declared) {
+    // skip: entrypoint has no db to check
+    if (context.db === undefined)
+        return;
+    const expected = declared ?? DEFAULT_ROW_LEVEL_SECURITY_MODE;
+    const actual = rowLevelSecurityModeOf(context.db);
+    if (actual !== expected) {
+        throw new InternalError({
+            message: `Entrypoint rowLevelSecurity is "${expected}" but the database connection runs in "${actual}" mode; open the pools with the same mode`,
+            details: { expected, actual },
+        });
+    }
+}

package/dist/env/dry-run-internals.d.ts

@@ -0,0 +1,10 @@
+export type DryRunOptions = {
+    /** From composeEnvSchema. Drives the per-row feature-attribution. */
+    readonly sources?: Readonly<Record<string, string>>;
+    /** Prefix for `pulumi config set <prefix>…` keys. Default "". */
+    readonly pulumiPrefix?: string;
+    /** k8s Secret name. Default "kumiko-env". */
+    readonly k8sName?: string;
+    /** k8s namespace. Default "default". */
+    readonly k8sNamespace?: string;
+};

package/dist/env/dry-run-internals.js

@@ -0,0 +1 @@
+export {};

package/dist/env/dry-run.d.ts

@@ -1,3 +1,4 @@
+import type { DryRunOptions } from "./dry-run-internals.ts";
 import { type ComposedEnvSchema, type EnvFieldInspection } from "./index.ts";
 export type DryRunMode = "human" | "json" | "pulumi" | "k8s";
 /** `boot` runs the boot validators without connecting anywhere; the other
@@ -10,16 +11,6 @@ export declare function parseDryRunEnvMode(raw: string | undefined): DryRunEnvMo
 /** True while any dry-run mode is requested, for code that runs at module
  *  load (key providers, secret derivation) and must not throw on missing env. */
 export declare function isDryRunEnvActive(env: Readonly<Record<string, string | undefined>>): boolean;
-export type DryRunOptions = {
-    /** From composeEnvSchema. Drives the per-row feature-attribution. */
-    readonly sources?: Readonly<Record<string, string>>;
-    /** Prefix for `pulumi config set <prefix>…` keys. Default "". */
-    readonly pulumiPrefix?: string;
-    /** k8s Secret name. Default "kumiko-env". */
-    readonly k8sName?: string;
-    /** k8s namespace. Default "default". */
-    readonly k8sNamespace?: string;
-};
 export declare function renderDryRun(composed: ComposedEnvSchema, mode: DryRunMode, options?: DryRunOptions): string;
 /** Table for `KUMIKO_DRY_RUN_ENV=boot`: one row per variable with its source,
  *  whether it is required, and whether it is set. Values are never printed. */

package/dist/env/dry-run.js

@@ -8,7 +8,8 @@
 // The same schema introspection (`classifyField`, `readKumikoMeta`) used
 // by parseEnv drives the output here — single source of truth.
 import { zodShape } from "./_zod-introspect.js";
-import { classifyField, getDefaultValue, getFieldDescription, pulumiConfigKey, readKumikoMeta, } from "./index.js";
+import { classifyField, readKumikoMeta, } from "./index.js";
+import { getDefaultValue, getFieldDescription, pulumiConfigKey } from "./internals.js";
 export const DRY_RUN_ENV_VAR = "KUMIKO_DRY_RUN_ENV";
 /** Reads `KUMIKO_DRY_RUN_ENV`. `1` and `true` mean `human`; an unknown value
  *  returns undefined, so the caller decides whether to warn or boot. */

package/dist/env/index.d.ts

@@ -1,33 +1,11 @@
 import * as z from "zod";
 import type { FeatureDefinition } from "../engine/types/feature.ts";
-export type KumikoEnvMeta = {
-    readonly pulumi?: {
-        /** Override the auto-derived camelCase Pulumi-config-key name. Apps
-         *  setting `pulumiPrefix: "studio"` and authoring `STUDIO_ADMIN_EMAIL`
-         *  would otherwise get `studioStudioAdminEmail` — set
-         *  `.meta({ kumiko: { pulumi: { name: "adminEmail" } } })` to drop the
-         *  duplicated prefix. */
-        readonly name?: string;
-        /** Shell expression that generates a value, e.g. `openssl rand -base64 32`.
-         *  Without this, dry-run-pulumi emits `<set-me>` as the placeholder. */
-        readonly generator?: string;
-        /** Force the `--secret` flag in `pulumi config set`. Default false. */
-        readonly secret?: boolean;
-    };
-    /** The value may be delivered as a Scaleway Key Manager ciphertext in
-     *  `<NAME>_CIPHERTEXT`. `runProdApp` decrypts it at boot when `<NAME>` itself
-     *  is unset; a set plaintext always wins. A flag, not an object: every slot
-     *  uses the same `_CIPHERTEXT` twin and one shared key (`PLATFORM_KEK_KMS_*`). */
-    readonly kms?: true;
-};
+import { type ComposedEnvShape, type ComposeEnvSchemaOptions, type EmptyShape, type EnvError, type EnvFieldClass, type EnvFieldStatus, type KumikoEnvMeta, type ParseEnvOptions } from "./internals.ts";
 export declare function readKumikoMeta(field: z.ZodType): KumikoEnvMeta;
 /** Env names whose schema field declares `kms: true` — the slots
  *  `resolvePlatformKeks` resolves from a ciphertext. */
 export declare function kmsSlotsOf(schema: z.ZodObject<z.ZodRawShape>): readonly string[];
-export type EnvFieldClass = "required" | "optional" | "withDefault";
 export declare function classifyField(field: z.ZodType): EnvFieldClass;
-export declare function getDefaultValue(field: z.ZodType): unknown;
-export declare function getFieldDescription(field: z.ZodType): string | undefined;
 /** A feature whose registered env schema is visible in its type, so
  *  `composeEnvSchema` can type the merged schema from the feature list. */
 export type FeatureWithEnvSchema<TFeature extends FeatureDefinition, TShape extends z.ZodRawShape> = TFeature & {
@@ -37,41 +15,6 @@ export type FeatureWithEnvSchema<TFeature extends FeatureDefinition, TShape exte
  *  `r.envSchema(schema)`. Throws when the feature registered another
  *  instance, so the type never claims fields the runtime schema lacks. */
 export declare function featureWithEnvSchema<TFeature extends FeatureDefinition, TShape extends z.ZodRawShape>(feature: TFeature, schema: z.ZodObject<TShape>): FeatureWithEnvSchema<TFeature, TShape>;
-type EmptyShape = Record<never, never>;
-type DeclaredEnvShape<TFeature> = TFeature extends {
-    readonly envSchema: z.ZodObject<infer TShape extends z.ZodRawShape>;
-} ? string extends keyof TShape ? EmptyShape : TShape : EmptyShape;
-type UnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
-type OptionalShape<TShape extends z.ZodRawShape> = {
-    [Key in keyof TShape]: z.ZodOptional<TShape[Key]>;
-};
-type FeaturesEnvShape<TFeatures extends readonly FeatureDefinition[]> = UnionToIntersection<DeclaredEnvShape<TFeatures[number]>>;
-type FlattenShape<TShape> = {
-    [Key in keyof TShape]: TShape[Key];
-} & {};
-type KnownShape<TShape extends z.ZodRawShape> = string extends keyof TShape ? EmptyShape : TShape;
-/** The merged shape `composeEnvSchema` returns. With `optionalFeatures`
- *  every feature field is typed optional: the type cannot tell which feature
- *  a name refers to, and over-reporting `undefined` is the safe side. */
-export type ComposedEnvShape<TFeatures extends readonly FeatureDefinition[], TCore extends z.ZodRawShape, TExtend extends z.ZodRawShape, TOptionalFeatures extends readonly string[] | undefined> = Extract<FlattenShape<KnownShape<TCore> & (TOptionalFeatures extends readonly string[] ? OptionalShape<FeaturesEnvShape<TFeatures> & z.ZodRawShape> : FeaturesEnvShape<TFeatures>) & KnownShape<TExtend>>, z.ZodRawShape>;
-export type ComposeEnvSchemaOptions<TFeatures extends readonly FeatureDefinition[] = readonly FeatureDefinition[], TCore extends z.ZodRawShape = z.ZodRawShape, TExtend extends z.ZodRawShape = z.ZodRawShape, TOptionalFeatures extends readonly string[] | undefined = readonly string[] | undefined> = {
-    /** All features whose envSchemas should be merged. Bundled features type
-     *  their fragment, so passing the list inline types the merged schema. */
-    readonly features: TFeatures;
-    /** App-specific env-vars (e.g. `STUDIO_ADMIN_EMAIL`). Keys here are
-     *  tagged as source "app" in the resulting sources map. */
-    readonly extend?: z.ZodObject<TExtend>;
-    /** Feature-names whose env-vars should be auto-`.optional()`-wrapped.
-     *  Lets an app opt out of e.g. `channel-email-smtp`'s vars without
-     *  manually `.partial()`-ing each shape at the call-site. */
-    readonly optionalFeatures?: TOptionalFeatures;
-    /** Framework-core env-vars (PORT, DATABASE_URL, REDIS_URL, …) from
-     *  `@cosmicdrift/kumiko-dev-server`. Keys here are tagged as source
-     *  "framework-core" in error output. Conflict-detection runs across
-     *  core/features/extend as one merged pool — same key declared in two
-     *  layers throws KumikoBootError at compose-time. */
-    readonly core?: z.ZodObject<TCore>;
-};
 export type ComposedEnvSchema<TShape extends z.ZodRawShape = z.ZodRawShape> = {
     /** The merged Zod schema, typed from core, the typed feature fragments and
      *  extend; `parseEnv(composed.schema, env)` returns the typed env. */
@@ -84,33 +27,11 @@ export type ComposedEnvSchema<TShape extends z.ZodRawShape = z.ZodRawShape> = {
  *  missing from the schema shape are ignored. */
 export declare function withOptionalEnvKeys(schema: z.ZodObject<z.ZodRawShape>, keys: readonly string[]): z.ZodObject<z.ZodRawShape>;
 export declare function composeEnvSchema<const TFeatures extends readonly FeatureDefinition[], TCore extends z.ZodRawShape = EmptyShape, TExtend extends z.ZodRawShape = EmptyShape, const TOptionalFeatures extends readonly string[] | undefined = undefined>(options: ComposeEnvSchemaOptions<TFeatures, TCore, TExtend, TOptionalFeatures>): ComposedEnvSchema<ComposedEnvShape<TFeatures, TCore, TExtend, TOptionalFeatures>>;
-export type EnvErrorKind = "missing" | "invalid";
-export type EnvError = {
-    readonly name: string;
-    readonly kind: EnvErrorKind;
-    readonly message: string;
-    /** Declaring source-name from `composeEnvSchema`'s sources map:
-     *  feature-name, "app" from `extend`, or "framework-core" from `core`.
-     *  Populated when parseEnv received `options.sources`. Surfaced by
-     *  `KumikoBootError.format()` so operators see WHICH source wants the
-     *  missing var, not just the var name. */
-    readonly source?: string;
-    /** "Set via: pulumi config set ..." line. Computed when pulumiPrefix is
-     *  passed to parseEnv. */
-    readonly suggestion?: string;
-};
 export declare class KumikoBootError extends Error {
     readonly errors: readonly EnvError[];
     constructor(errors: readonly EnvError[]);
     format(): string;
 }
-export type ParseEnvOptions = {
-    /** From composeEnvSchema's return — enables per-var feature-source
-     *  attribution in suggestions. */
-    readonly sources?: Readonly<Record<string, string>>;
-    /** When set, error suggestions include `pulumi config set <prefix>...`. */
-    readonly pulumiPrefix?: string;
-};
 /** Validates `env` against `schema` and throws KumikoBootError on any issue.
  *  A `kms: true` field delivered only as `<NAME>_CIPHERTEXT` passes validation but
  *  is `undefined` in the result despite its `string` type — it is only set once
@@ -124,7 +45,6 @@ export declare function parseEnv<S extends z.ZodObject<z.ZodRawShape>>(schema: S
  *  every access silently returned undefined and the compiler could not detect
  *  it. */
 export declare function parseEnvDryRun<S extends z.ZodObject<z.ZodRawShape>>(schema: S, env: Record<string, string | undefined>): Partial<z.infer<S>>;
-export type EnvFieldStatus = "set" | "unset" | "missing" | "invalid";
 export type EnvFieldInspection = {
     readonly name: string;
     readonly klass: EnvFieldClass;
@@ -138,7 +58,3 @@ export type EnvFieldInspection = {
  *  renders on an empty env. Object-level refinements do not run here; once
  *  nothing is missing or invalid, parseEnv validates the whole object. */
 export declare function inspectEnv(schema: z.ZodObject<z.ZodRawShape>, env: Readonly<Record<string, string | undefined>>, options?: Pick<ParseEnvOptions, "sources">): readonly EnvFieldInspection[];
-export declare function camelCase(snakeShout: string): string;
-export declare function pulumiConfigKey(envName: string, field: z.ZodType | undefined, prefix: string | undefined): string;
-export declare function buildPulumiSuggestion(envName: string, field: z.ZodType, prefix: string | undefined): string | undefined;
-export {};

package/dist/env/index.js

@@ -14,7 +14,9 @@
 // Without meta, defaults: `camelCase(envVarName)` for the Pulumi key,
 // `<set-me>` placeholder for the value, no `--secret` flag.
 import * as z from "zod";
-import { zodDef, zodDescription, zodMeta, zodShape, zodShapeField } from "./_zod-introspect.js";
+import { zodDef, zodMeta, zodShape, zodShapeField } from "./_zod-introspect.js";
+import { buildPulumiSuggestion, getFieldDescription, } from "./internals.js";
+// --- Per-env-var metadata (attach via Zod's `.meta()`) ---
 function isKumikoMeta(value) {
     if (value === null || typeof value !== "object")
         return false;
@@ -70,6 +72,7 @@ function relaxCiphertextOnlySlots(schema, env) {
     }
     return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
 }
+// --- Field-classification helpers (Zod v4 introspection) ---
 export function classifyField(field) {
     // Drill through ZodEffects/ZodPipe wrappers to find the inner kind.
     let current = field;
@@ -104,29 +107,6 @@ export function classifyField(field) {
     }
     return "required";
 }
-export function getDefaultValue(field) {
-    let current = field;
-    for (let i = 0; i < 8; i++) {
-        if (current instanceof z.ZodDefault) {
-            // Zod v4: defaultValue is the raw value (v3 was a factory function).
-            // Support both shapes for forward/backward safety.
-            const raw = zodDef(current)?.defaultValue;
-            // @cast-boundary schema-walk — Zod v3 stored a thunk, v4 a raw value
-            return typeof raw === "function" ? raw() : raw;
-        }
-        const inner = zodDef(current);
-        if (inner?.innerType) {
-            current = inner.innerType;
-            continue;
-        }
-        break;
-    }
-    return undefined;
-}
-// @wrapper-known semantic-alias
-export function getFieldDescription(field) {
-    return zodDescription(field);
-}
 function registersEnvSchema(feature, schema) {
     return feature.envSchema === schema;
 }
@@ -262,6 +242,7 @@ export function composeEnvSchema(options) {
     const schema = z.object(merged);
     return { schema, sources };
 }
+// --- Errors ---
 function formatBootError(errors) {
     const lines = [
         `Boot failed: ${errors.length} env-var problem${errors.length === 1 ? "" : "s"}`,
@@ -291,6 +272,7 @@ export class KumikoBootError extends Error {
         return formatBootError(this.errors);
     }
 }
+// --- Parse ---
 // safeParse does not catch exceptions thrown inside refinements; a refinement
 // reading a ciphertext-only slot (undefined here) would otherwise escape as a raw
 // TypeError past the KumikoBootError mapping.
@@ -353,9 +335,6 @@ export function parseEnv(schema, env, options = {}) {
     throw new KumikoBootError(errors);
 }
 // --- Pulumi-suggestion ---
-function ucfirst(s) {
-    return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
-}
 /** Dry-run counterpart to parseEnv (KUMIKO_DRY_RUN_ENV path): parses each
  *  field individually and returns an honest Partial — present values pass
  *  through with their types (coerced), while missing or invalid values are
@@ -416,26 +395,3 @@ function firstFieldIssue(field, raw) {
         return "a field refinement threw while checking the value";
     }
 }
-export function camelCase(snakeShout) {
-    const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
-    if (parts.length === 0)
-        return snakeShout.toLowerCase();
-    return parts[0] + parts.slice(1).map(ucfirst).join("");
-}
-export function pulumiConfigKey(envName, field, prefix) {
-    const meta = field ? readKumikoMeta(field) : {};
-    if (meta.pulumi?.name) {
-        return prefix ? prefix + ucfirst(meta.pulumi.name) : meta.pulumi.name;
-    }
-    const camel = camelCase(envName);
-    return prefix ? prefix + ucfirst(camel) : camel;
-}
-export function buildPulumiSuggestion(envName, field, prefix) {
-    if (!prefix)
-        return undefined;
-    const meta = readKumikoMeta(field);
-    const key = pulumiConfigKey(envName, field, prefix);
-    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
-    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
-    return `Set via: pulumi config set${secretFlag} ${key} ${value}`;
-}

package/dist/env/internals.d.ts

@@ -0,0 +1,87 @@
+import * as z from "zod";
+import type { FeatureDefinition } from "../engine/types/feature.ts";
+export type KumikoEnvMeta = {
+    readonly pulumi?: {
+        /** Override the auto-derived camelCase Pulumi-config-key name. Apps
+         *  setting `pulumiPrefix: "studio"` and authoring `STUDIO_ADMIN_EMAIL`
+         *  would otherwise get `studioStudioAdminEmail` — set
+         *  `.meta({ kumiko: { pulumi: { name: "adminEmail" } } })` to drop the
+         *  duplicated prefix. */
+        readonly name?: string;
+        /** Shell expression that generates a value, e.g. `openssl rand -base64 32`.
+         *  Without this, dry-run-pulumi emits `<set-me>` as the placeholder. */
+        readonly generator?: string;
+        /** Force the `--secret` flag in `pulumi config set`. Default false. */
+        readonly secret?: boolean;
+    };
+    /** The value may be delivered as a Scaleway Key Manager ciphertext in
+     *  `<NAME>_CIPHERTEXT`. `runProdApp` decrypts it at boot when `<NAME>` itself
+     *  is unset; a set plaintext always wins. A flag, not an object: every slot
+     *  uses the same `_CIPHERTEXT` twin and one shared key (`PLATFORM_KEK_KMS_*`). */
+    readonly kms?: true;
+};
+export type EnvFieldClass = "required" | "optional" | "withDefault";
+export declare function getDefaultValue(field: z.ZodType): unknown;
+export declare function getFieldDescription(field: z.ZodType): string | undefined;
+export type EmptyShape = Record<never, never>;
+export type DeclaredEnvShape<TFeature> = TFeature extends {
+    readonly envSchema: z.ZodObject<infer TShape extends z.ZodRawShape>;
+} ? string extends keyof TShape ? EmptyShape : TShape : EmptyShape;
+export type UnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+export type OptionalShape<TShape extends z.ZodRawShape> = {
+    [Key in keyof TShape]: z.ZodOptional<TShape[Key]>;
+};
+export type FeaturesEnvShape<TFeatures extends readonly FeatureDefinition[]> = UnionToIntersection<DeclaredEnvShape<TFeatures[number]>>;
+export type FlattenShape<TShape> = {
+    [Key in keyof TShape]: TShape[Key];
+} & {};
+export type KnownShape<TShape extends z.ZodRawShape> = string extends keyof TShape ? EmptyShape : TShape;
+/** The merged shape `composeEnvSchema` returns. With `optionalFeatures`
+ *  every feature field is typed optional: the type cannot tell which feature
+ *  a name refers to, and over-reporting `undefined` is the safe side. */
+export type ComposedEnvShape<TFeatures extends readonly FeatureDefinition[], TCore extends z.ZodRawShape, TExtend extends z.ZodRawShape, TOptionalFeatures extends readonly string[] | undefined> = Extract<FlattenShape<KnownShape<TCore> & (TOptionalFeatures extends readonly string[] ? OptionalShape<FeaturesEnvShape<TFeatures> & z.ZodRawShape> : FeaturesEnvShape<TFeatures>) & KnownShape<TExtend>>, z.ZodRawShape>;
+export type ComposeEnvSchemaOptions<TFeatures extends readonly FeatureDefinition[] = readonly FeatureDefinition[], TCore extends z.ZodRawShape = z.ZodRawShape, TExtend extends z.ZodRawShape = z.ZodRawShape, TOptionalFeatures extends readonly string[] | undefined = readonly string[] | undefined> = {
+    /** All features whose envSchemas should be merged. Bundled features type
+     *  their fragment, so passing the list inline types the merged schema. */
+    readonly features: TFeatures;
+    /** App-specific env-vars (e.g. `STUDIO_ADMIN_EMAIL`). Keys here are
+     *  tagged as source "app" in the resulting sources map. */
+    readonly extend?: z.ZodObject<TExtend>;
+    /** Feature-names whose env-vars should be auto-`.optional()`-wrapped.
+     *  Lets an app opt out of e.g. `channel-email-smtp`'s vars without
+     *  manually `.partial()`-ing each shape at the call-site. */
+    readonly optionalFeatures?: TOptionalFeatures;
+    /** Framework-core env-vars (PORT, DATABASE_URL, REDIS_URL, …) from
+     *  `@cosmicdrift/kumiko-dev-server`. Keys here are tagged as source
+     *  "framework-core" in error output. Conflict-detection runs across
+     *  core/features/extend as one merged pool — same key declared in two
+     *  layers throws KumikoBootError at compose-time. */
+    readonly core?: z.ZodObject<TCore>;
+};
+export type EnvErrorKind = "missing" | "invalid";
+export type EnvError = {
+    readonly name: string;
+    readonly kind: EnvErrorKind;
+    readonly message: string;
+    /** Declaring source-name from `composeEnvSchema`'s sources map:
+     *  feature-name, "app" from `extend`, or "framework-core" from `core`.
+     *  Populated when parseEnv received `options.sources`. Surfaced by
+     *  `KumikoBootError.format()` so operators see WHICH source wants the
+     *  missing var, not just the var name. */
+    readonly source?: string;
+    /** "Set via: pulumi config set ..." line. Computed when pulumiPrefix is
+     *  passed to parseEnv. */
+    readonly suggestion?: string;
+};
+export type ParseEnvOptions = {
+    /** From composeEnvSchema's return — enables per-var feature-source
+     *  attribution in suggestions. */
+    readonly sources?: Readonly<Record<string, string>>;
+    /** When set, error suggestions include `pulumi config set <prefix>...`. */
+    readonly pulumiPrefix?: string;
+};
+export declare function ucfirst(s: string): string;
+export type EnvFieldStatus = "set" | "unset" | "missing" | "invalid";
+export declare function camelCase(snakeShout: string): string;
+export declare function pulumiConfigKey(envName: string, field: z.ZodType | undefined, prefix: string | undefined): string;
+export declare function buildPulumiSuggestion(envName: string, field: z.ZodType, prefix: string | undefined): string | undefined;

package/dist/env/internals.js

@@ -0,0 +1,53 @@
+import * as z from "zod";
+import { zodDef, zodDescription } from "./_zod-introspect.js";
+import { readKumikoMeta } from "./index.js";
+export function getDefaultValue(field) {
+    let current = field;
+    for (let i = 0; i < 8; i++) {
+        if (current instanceof z.ZodDefault) {
+            // Zod v4: defaultValue is the raw value (v3 was a factory function).
+            // Support both shapes for forward/backward safety.
+            const raw = zodDef(current)?.defaultValue;
+            // @cast-boundary schema-walk — Zod v3 stored a thunk, v4 a raw value
+            return typeof raw === "function" ? raw() : raw;
+        }
+        const inner = zodDef(current);
+        if (inner?.innerType) {
+            current = inner.innerType;
+            continue;
+        }
+        break;
+    }
+    return undefined;
+}
+// @wrapper-known semantic-alias
+export function getFieldDescription(field) {
+    return zodDescription(field);
+}
+// --- Pulumi-suggestion ---
+export function ucfirst(s) {
+    return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+export function camelCase(snakeShout) {
+    const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
+    if (parts.length === 0)
+        return snakeShout.toLowerCase();
+    return parts[0] + parts.slice(1).map(ucfirst).join("");
+}
+export function pulumiConfigKey(envName, field, prefix) {
+    const meta = field ? readKumikoMeta(field) : {};
+    if (meta.pulumi?.name) {
+        return prefix ? prefix + ucfirst(meta.pulumi.name) : meta.pulumi.name;
+    }
+    const camel = camelCase(envName);
+    return prefix ? prefix + ucfirst(camel) : camel;
+}
+export function buildPulumiSuggestion(envName, field, prefix) {
+    if (!prefix)
+        return undefined;
+    const meta = readKumikoMeta(field);
+    const key = pulumiConfigKey(envName, field, prefix);
+    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+    return `Set via: pulumi config set${secretFlag} ${key} ${value}`;
+}

package/dist/errors/classes.js

@@ -201,14 +201,14 @@ export class InternalError extends KumikoError {
         });
     }
 }
-// A ctx.queryAsMember read ran into its statement timeout (SQLSTATE 57014). Reuses the generic
+// A ctx.dispatch.queryAsMember read ran into its statement timeout (SQLSTATE 57014). Reuses the generic
 // errors.internal i18n key: the client can do nothing but retry, and the code is for log/alert routing.
 export class MemberReadTimeoutError extends KumikoError {
     code = "member_read_timeout";
     httpStatus = 504;
     constructor(opts) {
         super({
-            message: `ctx.queryAsMember read exceeded its ${opts.timeoutMs}ms statement timeout`,
+            message: `ctx.dispatch.queryAsMember read exceeded its ${opts.timeoutMs}ms statement timeout`,
             i18nKey: "errors.internal",
             ...(opts.cause && { cause: opts.cause }),
         });

package/dist/errors/index.d.ts

@@ -1,18 +1,9 @@
-export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.ts";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, RecordLockedError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.ts";
+export type { FieldIssue } from "./classes.ts";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, InternalError, NotFoundError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.ts";
 export type { ErrorDocsConfig } from "./docs-url.ts";
-export { resolveErrorDocsUrl } from "./docs-url.ts";
-export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.ts";
 export { isKumikoError, KumikoError } from "./kumiko-error.ts";
-export { memberResolutionReadOnlyDenied } from "./member-resolution.ts";
-export type { AgentReason, FrameworkReason } from "./reasons.ts";
-export { AgentReasons, FrameworkReasons } from "./reasons.ts";
-export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.ts";
-export { buildErrorLog, serializeError } from "./serialize.ts";
-export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.ts";
-export { toKumikoError } from "./to-kumiko-error.ts";
-export type { InvalidTransitionDetails } from "./transition-details.ts";
-export { buildInvalidTransitionDetails } from "./transition-details.ts";
+export { FrameworkReasons } from "./reasons.ts";
+export { subjectErasedConflict } from "./subject-erased.ts";
 export type { WriteErrorInfo, WriteFailure } from "./write-error-info.ts";
-export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.ts";
+export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, writeFailure, } from "./write-error-info.ts";
 export { validationErrorFromZod } from "./zod-bridge.ts";

package/dist/errors/index.js

@@ -1,11 +1,6 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, RecordLockedError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
-export { resolveErrorDocsUrl } from "./docs-url.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, InternalError, NotFoundError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
-export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
-export { AgentReasons, FrameworkReasons } from "./reasons.js";
-export { buildErrorLog, serializeError } from "./serialize.js";
-export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.js";
-export { toKumikoError } from "./to-kumiko-error.js";
-export { buildInvalidTransitionDetails } from "./transition-details.js";
-export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";
+export { FrameworkReasons } from "./reasons.js";
+export { subjectErasedConflict } from "./subject-erased.js";
+export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, writeFailure, } from "./write-error-info.js";
 export { validationErrorFromZod } from "./zod-bridge.js";

package/dist/errors/member-resolution.js

@@ -3,7 +3,7 @@ import { FrameworkReasons } from "./reasons.js";
 // Lives in errors/ (not pipeline/) so db/tenant-db.ts can throw it without importing pipeline.
 export function memberResolutionReadOnlyDenied(cause) {
     return new AccessDeniedError({
-        message: "a resolved member principal (ctx.queryAsMember) cannot write or reach raw SQL — read-only",
+        message: "a resolved member principal (ctx.dispatch.queryAsMember) cannot write or reach raw SQL — read-only",
         details: { reason: FrameworkReasons.memberResolutionReadOnly },
         ...(cause instanceof Error && { cause }),
     });

package/dist/errors/reasons.d.ts

@@ -24,4 +24,3 @@ export declare const AgentReasons: {
     readonly iterationLimit: "agent.iteration_limit";
     readonly highRiskNoAlways: "agent.high_risk_no_always";
 };
-export type AgentReason = (typeof AgentReasons)[keyof typeof AgentReasons];

package/dist/errors/reasons.js

@@ -33,10 +33,10 @@ export const FrameworkReasons = {
     // Distinct from access-denied — clients should surface "feature X is
     // currently unavailable" not "you don't have permission".
     featureDisabled: "feature_disabled",
-    // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+    // AccessDeniedError: a handler/hook called ctx.dispatch.queryAs/ctx.dispatch.writeAs with a
     // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
     systemIdentitySwitchDenied: "system_identity_switch_denied",
-    // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+    // AccessDeniedError: a handler/hook called ctx.dispatch.queryAs/ctx.dispatch.writeAs with a
     // non-SYSTEM identity other than its own caller (different user, tenant,
     // claims, origin or extra roles) without r.systemScope() or escapeHatch.
     identitySwitchDenied: "identity_switch_denied",
@@ -44,13 +44,13 @@ export const FrameworkReasons = {
     tenantOverrideRequiresSystemAdmin: "tenant_override_requires_system_admin",
     // AccessDeniedError: ctx.notify was called with `to: { tenant }` naming a tenant other than the caller's.
     notifyForeignTenantBroadcast: "notify_foreign_tenant_broadcast",
-    // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
+    // AccessDeniedError: a handler/hook called ctx.dispatch.queryProjection(..., { unsafeAllTenants: true })
     // without an r.systemScope() feature or a declared escapeHatch.
     unsafeAllTenantsDenied: "unsafe_all_tenants_denied",
-    // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
+    // AccessDeniedError: ctx.dispatch.queryAsMember's userId is not an active member of
     // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
     memberResolutionDenied: "member_resolution_denied",
-    // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
+    // AccessDeniedError: a query handler invoked via ctx.dispatch.queryAsMember tried to
     // write — a resolved member principal is read-only by construction.
     memberResolutionReadOnly: "member_resolution_read_only",
     // AccessDeniedError: a write under an anonymous root touched a personal-data field
@@ -58,11 +58,11 @@ export const FrameworkReasons = {
     publicIntakeRequired: "public_intake_required",
     // AccessDeniedError: the directly-dispatched entry handler performs a hard
     // delete/forget but its agent.risk resolves below "high" — delegation via
-    // ctx.write/writeAs from a lower-risk handler does not inherit the gate.
+    // ctx.dispatch.write/writeAs from a lower-risk handler does not inherit the gate.
     irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk",
     // AccessDeniedError: the directly-dispatched entry handler writes a field
     // flagged readAsInstruction: true but its agent.risk resolves below "high" —
-    // delegation via ctx.write/writeAs from a lower-risk handler does not
+    // delegation via ctx.dispatch.write/writeAs from a lower-risk handler does not
     // inherit the gate.
     instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk",
     // ConflictError: a write touched a personal-data field of a data subject whose

package/dist/errors/serialize.d.ts

@@ -14,21 +14,3 @@ export type ErrorResponseBody = {
 };
 export declare const exposesCauseDetails: () => boolean;
 export declare function serializeError(err: KumikoError, requestId?: string, errorDocs?: ErrorDocsConfig): ErrorResponseBody;
-export type ErrorLogEntry = {
-    readonly name: string;
-    readonly code: string;
-    readonly httpStatus: number;
-    readonly message: string;
-    readonly i18nKey: string;
-    readonly details?: unknown;
-    readonly stack?: string;
-    readonly cause?: CauseSnapshot;
-};
-export declare function buildErrorLog(err: KumikoError): ErrorLogEntry;
-type CauseSnapshot = {
-    readonly name: string;
-    readonly message: string;
-    readonly stack?: string;
-    readonly cause?: CauseSnapshot;
-};
-export {};

package/dist/errors/serialize.js

@@ -53,30 +53,3 @@ export function serializeError(err, requestId, errorDocs) {
         },
     };
 }
-export function buildErrorLog(err) {
-    return {
-        name: err.name,
-        code: err.code,
-        httpStatus: err.httpStatus,
-        message: err.message,
-        i18nKey: err.i18nKey,
-        ...(err.details !== undefined && { details: err.details }),
-        ...(err.stack && { stack: err.stack }),
-        ...(err.cause !== undefined && { cause: serializeCause(err.cause) }),
-    };
-}
-const MAX_CAUSE_DEPTH = 10;
-function serializeCause(cause, depth = 0) {
-    if (depth >= MAX_CAUSE_DEPTH) {
-        return { name: "CauseChainTruncated", message: `depth >= ${MAX_CAUSE_DEPTH}` };
-    }
-    if (cause instanceof Error) {
-        return {
-            name: cause.name,
-            message: cause.message,
-            ...(cause.stack && { stack: cause.stack }),
-            ...(cause.cause !== undefined && { cause: serializeCause(cause.cause, depth + 1) }),
-        };
-    }
-    return { name: "NonError", message: String(cause) };
-}

package/dist/es-ops/index.d.ts

@@ -1,4 +1,4 @@
-export { type CreateSeedMigrationContextArgs, createSeedMigrationContext, } from "./context.ts";
-export { createEsOperationsTable, type EsOperationAppliedBy, type EsOperationType, esOperationsTable, } from "./operations-schema.ts";
-export { type RunPendingSeedMigrationsArgs, type RunPendingSeedMigrationsResult, runPendingSeedMigrations, } from "./runner.ts";
-export type { SeedMembershipRow, SeedMigration, SeedMigrationContext, SeedTemplateResourceFilter, SeedTemplateResourceRow, SeedTenantRow, SeedUserRow, } from "./types.ts";
+export { createSeedMigrationContext } from "./context.ts";
+export { createEsOperationsTable, esOperationsTable, } from "./operations-schema.ts";
+export { runPendingSeedMigrations } from "./runner.ts";
+export type { SeedMigration, SeedMigrationContext, } from "./types.ts";

package/dist/es-ops/index.js

@@ -7,6 +7,6 @@
 //   - `SeedMigration`: default export type of a seed file
 //   - `runProdApp({ seedsDir })`: the framework runs pending migrations at boot
 //   - `bunx kumiko ops seed:new|status|apply` (CLI)
-export { createSeedMigrationContext, } from "./context.js";
+export { createSeedMigrationContext } from "./context.js";
 export { createEsOperationsTable, esOperationsTable, } from "./operations-schema.js";
-export { runPendingSeedMigrations, } from "./runner.js";
+export { runPendingSeedMigrations } from "./runner.js";