@cosmicdrift/kumiko-framework 0.50.0 → 0.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.45.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.50.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"

package/src/engine/__tests__/boot-validator.test.ts

@@ -1521,6 +1521,26 @@ describe("boot-validator", () => {
       ).toThrow(/Config-Key "shop:config:typo-here" ist in keiner Feature-Registry deklariert/);
     });
 
+    test("camelCase-Quelle (multi-word) → kanonische kebab-QN matched, kein Throw", () => {
+      // Regression: r.config registriert den camelCase-Objekt-Key
+      // (brandingTitle), die echte QN ist aber `shop:config:branding-title`
+      // (define-feature toKebab't beides). Ein configEdit-Screen, der die
+      // kanonische kebab-QN referenziert, darf NICHT als "unbekannt" failen —
+      // ohne qualifyEntityName im Validator stand dort die rohe camelCase-QN.
+      const feature = defineFeature("shop", (r) => {
+        r.config({ keys: { brandingTitle: createTenantConfig("text", { default: "" }) } });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { title: "shop:config:branding-title" },
+          fields: { title: { type: "text" } } as never,
+          layout: { sections: [{ title: "Basics", fields: ["title"] }] } as never,
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
     test("extension section ohne component → Throw (Parität zu entityEdit)", () => {
       // synthesizeConfigEditScreen reicht die layout 1:1 an RenderEdit weiter —
       // eine Extension-Section ohne react/native-Marker rendert sonst stumm leer.
@@ -2124,11 +2144,11 @@ describe("boot-validator — config key backing × scope", () => {
     expect(() => validateBoot([feature])).toThrow(/backing="secrets".*requires scope="system"/i);
   });
 
-  test("rejects backing:secrets even system-scoped until the dispatch is wired (framework#333)", () => {
+  test("allows backing:secrets when system-scoped (dispatch is wired)", () => {
     const feature = defineFeature("billing", (r) => {
       r.config({ keys: { apiKey: createSystemConfig("text", { backing: "secrets" }) } });
     });
-    expect(() => validateBoot([feature])).toThrow(/not yet wired.*333/i);
+    expect(() => validateBoot([feature])).not.toThrow();
   });
 
   test("a config key without secrets backing boots fine", () => {

package/src/engine/boot-validator/config-deps.ts

@@ -151,14 +151,12 @@ export function validateConfigKeyBacking(feature: FeatureDefinition): void {
       );
     }
 
-    // The secrets read/write dispatch is not yet wired (framework#333). Until
-    // it lands, the value would silently persist in the config-values
-    // projection instead of the secrets store — losing the envelope-encryption,
-    // key-rotation and audit-on-read that backing="secrets" promises. Reject
-    // loudly rather than degrade to config-encrypted behind the declaration.
-    throw new Error(
-      `[Feature ${feature.name}] Config key "${keyName}" declares backing="secrets", but the secrets read/write dispatch is not yet wired (framework#333). Until then remove backing (the value would store as config-encrypted) or gate the feature behind #333.`,
-    );
+    // system-scoped backing="secrets" is wired end-to-end: reads dispatch
+    // through the resolver's secretsReader, writes through config:write:set/
+    // :reset into the secrets store (SYSTEM_TENANT_ID), masked in the query
+    // handlers. The runtime contract is that the app provides
+    // `extraContext.secrets` (+ a MasterKeyProvider) — a backing="secrets"
+    // read/write without it throws loud at request time, not silently.
   }
 }
 

package/src/engine/boot-validator/index.ts

@@ -1,3 +1,4 @@
+import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
 import {
@@ -58,14 +59,18 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   // Collect all config keys across features (for cross-feature reference validation)
   const allConfigKeys = new Set<string>();
-  // Qualified config-key set für ConfigEditScreen-Validation. Format
-  // wie in registry.ts: `<feature>:config:<short>`. allConfigKeys oben
-  // nutzt das ältere `feature.short`-Format für validateConfigReads.
+  // Qualified config-key set für ConfigEditScreen-Validation. MUSS via
+  // qualifyEntityName kanonisiert werden (toKebab auf Feature + Key) — exakt
+  // wie define-feature/registry den QN bildet. Der rohe f.configKeys-Key ist
+  // der camelCase-Objekt-Key (`brandingTitle`), die echte QN aber
+  // `…:config:branding-title`; ohne toKebab failt jeder configEdit-Screen mit
+  // multi-word Config-Key fälschlich. allConfigKeys oben nutzt das ältere
+  // `feature.short`-Format für validateConfigReads.
   const allConfigKeyQns = new Set<string>();
   for (const f of features) {
     for (const key of Object.keys(f.configKeys)) {
       allConfigKeys.add(`${f.name}.${key}`);
-      allConfigKeyQns.add(`${f.name}:config:${key}`);
+      allConfigKeyQns.add(qualifyEntityName(f.name, QnTypes.config, key));
     }
   }
 

package/src/engine/config-helpers.ts

@@ -64,6 +64,11 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
   encrypted?: boolean;
   options?: readonly string[]; // for select type
   bounds?: T extends "number" ? ConfigBounds : never;
+  // Regex enforced at write (set.write) — only meaningful for text keys
+  // (never for the other type-tags). Use anchored + length-bounded patterns:
+  // the value is tenant-supplied, so an unbounded backtracking regex is a
+  // ReDoS vector. See ConfigKeyDefinition.pattern.
+  pattern?: T extends "text" ? { regex: string; flags?: string } : never;
   computed?: ConfigComputedFn<T>;
   allowPerRequest?: T extends "text" ? never : boolean;
   required?: boolean;
@@ -100,6 +105,7 @@ function createConfigKey<T extends ConfigKeyType>(
     ...(opts.encrypted ? { encrypted: true } : {}),
     ...(opts.options ? { options: opts.options } : {}),
     bounds: opts.bounds as ConfigBounds | undefined, // @cast-boundary schema-walk
+    ...(opts.pattern ? { pattern: opts.pattern } : {}),
     computed: opts.computed,
     ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
     ...(opts.required === true ? { required: true } : {}),

package/src/engine/feature-manifest.ts

@@ -19,6 +19,10 @@ export type ManifestConfigKey = {
   readonly computed: boolean;
   readonly options: readonly string[] | null;
   readonly bounds: { readonly min?: number; readonly max?: number } | null;
+  // Serializable write-time validator for type="text" keys (hex/https/length).
+  // Carried into the manifest as ConfigKeyDefinition.pattern's JSDoc promises
+  // (feature-manifest, docgen) — was previously dropped by this serializer.
+  readonly pattern: { readonly regex: string; readonly flags?: string } | null;
   readonly writeRoles: readonly string[];
   readonly readRoles: readonly string[];
 };
@@ -96,6 +100,7 @@ export function buildManifestFromRegistry(
         computed: def.computed !== undefined,
         options: def.options ?? null,
         bounds: def.bounds ?? null,
+        pattern: def.pattern ?? null,
         writeRoles: def.access.write,
         readRoles: def.access.read,
       });

package/src/engine/index.ts

@@ -233,6 +233,7 @@ export type {
   ConfigMask,
   ConfigResolver,
   ConfigScope,
+  ConfigSecretsReader,
   ConfigSeedDef,
   ConfigStoredRow,
   ConfigStoredRowWithSource,

package/src/engine/types/config.ts

@@ -73,6 +73,16 @@ export type ConfigComputedFn<T extends ConfigKeyType = ConfigKeyType> = (
 // Tenant-Override. Die backing×scope-Matrix erzwingt der boot-validator.
 export type ConfigBacking = "config" | "secrets";
 
+// Minimal read surface the config resolver needs to dispatch a
+// backing="secrets" key to the secrets store, without coupling the engine
+// types to the full SecretsContext. The app's `ctx.secrets` (a SecretsContext)
+// is structurally assignable. Threaded per-call (not at resolver construction)
+// because the resolver is framework-auto-created while `ctx.secrets` is
+// app-provided — only the request context sees both.
+export type ConfigSecretsReader = {
+  get(tenantId: TenantId, key: string): Promise<{ readonly reveal: () => string } | undefined>;
+};
+
 export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   readonly type: T;
   readonly default?: ConfigValue<T>;
@@ -81,6 +91,15 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   readonly encrypted?: boolean;
   readonly options?: readonly string[];
   readonly bounds?: ConfigBounds;
+  // Per-key string-pattern validation for type="text". The value must match
+  // the regex at write time — set.write hard-rejects a mismatch with
+  // ValidationError("invalid_format"), same posture as bounds. Stored as a
+  // serializable {regex, flags} pair (not a RegExp/predicate) so it survives
+  // JSON like `bounds`/`options` (feature-manifest, docgen) and compiles per
+  // write via new RegExp. Keep patterns anchored + length-bounded: the value
+  // is tenant-supplied (untrusted), an unbounded catastrophic-backtracking
+  // regex applied to it would be a ReDoS vector.
+  readonly pattern?: { readonly regex: string; readonly flags?: string };
   readonly computed?: ConfigComputedFn<T>;
   // Per-Request opt-in. Default false — resolveConfigOrParam wirft für
   // Keys ohne diese Marke, auch wenn der Caller paramValue übergibt. Das
@@ -145,6 +164,10 @@ export type ConfigAccessor = {
 export type ConfigAccessorFactory = (deps: {
   readonly user: { readonly id: string; readonly tenantId: TenantId };
   readonly db: DbConnection | TenantDb;
+  // Present when the app wired `extraContext.secrets`. Lets the internal
+  // `ctx.config.get` read a backing="secrets" key transparently from the
+  // secrets store; absent → a backing="secrets" read throws loud.
+  readonly secrets?: ConfigSecretsReader;
 }) => ConfigAccessor;
 
 // Row shape returned by ConfigResolver.getAll — just enough for the
@@ -218,6 +241,7 @@ export type ConfigResolver = {
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<string | number | boolean | undefined>;
 
   // Same cascade as get() but also reports which layer produced the value.
@@ -231,6 +255,7 @@ export type ConfigResolver = {
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<ConfigValueWithSource>;
 
   getAll(
@@ -259,17 +284,21 @@ export type ConfigResolver = {
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<ConfigCascade>;
 
   // Batch variant: resolves cascades for N keys in one DB round-trip.
   // keyDefs must contain definitions for every key in the keys array.
-  // Returns a map of qualifiedKey → ConfigCascade.
+  // Returns a map of qualifiedKey → ConfigCascade. backing="secrets" keys
+  // resolve their system rung from the secrets store via secretsReader
+  // (one read each — they are system-only and rare).
   getCascadeBatch(
     keys: readonly string[],
     keyDefs: ReadonlyMap<string, ConfigKeyDefinition>,
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<ReadonlyMap<string, ConfigCascade>>;
 };
 

package/src/engine/types/index.ts

@@ -25,6 +25,7 @@ export type {
   ConfigKeyType,
   ConfigMask,
   ConfigResolver,
+  ConfigSecretsReader,
   ConfigSeedDef,
   ConfigStoredRow,
   ConfigStoredRowWithSource,

package/src/jobs/job-runner.ts

@@ -299,6 +299,10 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     const triggerName = rawData["_triggerName"] as string | undefined; // @cast-boundary dynamic-key
     const jobContext: AppContext = {
       ...context,
+      // The runner owns the registry it resolved this job from — expose it so
+      // workers can reach projections/jobs without the app author duplicating
+      // it into `context` (the JobContext contract guarantees `registry`).
+      registry,
       systemUser: createSystemUser(tenantId),
       triggeredBy: triggeredById !== null ? { id: triggeredById, tenantId } : null,
       log: createJobLogger(logs),

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -30,6 +30,7 @@ import {
   unsafePushTables,
 } from "../../stack";
 import {
+  enqueueProjectionRebuild,
   listPendingRebuilds,
   queueRebuildsFromMarkers,
   runPendingRebuilds,
@@ -226,3 +227,24 @@ describe("pending-rebuilds queue", () => {
     expect(await getCount()).toBe(1);
   });
 });
+
+// #362: der framework-Helper. Ohne jobs-Feature (kein jobRunner) rebuildet er
+// synchron inline — das heutige Verhalten, garantiert framework-pur. Der
+// dispatch-Pfad (mit jobs) lebt in jobs/__tests__/projection-rebuild-job.*.
+describe("enqueueProjectionRebuild — inline fallback (no jobs feature)", () => {
+  test("without a jobRunner, rebuilds the projection synchronously", async () => {
+    await executor.create({ groupId: GROUP, name: "a" }, admin, tdb);
+    await executor.create({ groupId: GROUP, name: "b" }, admin, tdb);
+
+    const outcome = await enqueueProjectionRebuild("pendingtest:projection:pending-counts", {
+      db: testDb.db,
+      registry,
+    });
+
+    expect(outcome.mode).toBe("inline");
+    if (outcome.mode === "inline") {
+      expect(outcome.result.eventsProcessed).toBe(2);
+    }
+    expect(await getCount()).toBe(2);
+  });
+});

package/src/migrations/index.ts

@@ -10,8 +10,12 @@ export {
 // Persistente Pending-Rebuild-Queue (survives Rebuild-Failures + Crashes).
 export {
   createPendingRebuildsTable,
+  type EnqueueProjectionRebuildDeps,
+  type EnqueueProjectionRebuildResult,
+  enqueueProjectionRebuild,
   listPendingRebuilds,
   type PendingRebuildRun,
+  PROJECTION_REBUILD_JOB,
   pendingRebuildsTable,
   queueRebuildsFromMarkers,
   type RunPendingRebuildsOptions,

package/src/migrations/pending-rebuilds.ts

@@ -17,8 +17,9 @@ import { deleteMany, selectMany, upsertOnConflict } from "../db/query";
 import { readRebuildMarker } from "../db/rebuild-marker";
 import { tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
+import type { JobRunner } from "../jobs";
 import { createFallbackLogger } from "../logging/utils";
-import { rebuildProjection } from "../pipeline";
+import { type RebuildResult, rebuildProjection } from "../pipeline";
 import { unsafePushTables } from "../stack";
 import { buildProjectionTableIndex } from "./projection-table-index";
 
@@ -163,3 +164,37 @@ export async function runPendingRebuilds(
   }
   return { rebuilt, failed, unmapped, unresolvedManaged };
 }
+
+// Qualified name of the framework-provided projection-rebuild job. Registered
+// by the `jobs` bundled-feature (createJobsFeature) → available whenever jobs
+// is composed. A jobs-less boot has no jobRunner and rebuilds inline instead.
+export const PROJECTION_REBUILD_JOB = "jobs:job:projection-rebuild";
+
+export type EnqueueProjectionRebuildResult =
+  | { readonly mode: "dispatched"; readonly bullJobId: string }
+  | { readonly mode: "inline"; readonly result: RebuildResult };
+
+export type EnqueueProjectionRebuildDeps = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  // Present + projection-rebuild job registered (jobs composed) → tracked,
+  // retryable job (read_job_runs + read_job_run_logs). Absent → inline rebuild.
+  readonly jobRunner?: JobRunner;
+};
+
+/** Triggert einen Single-Projection-Rebuild. Mit `jobs`-Feature (jobRunner +
+ *  registriertem Job) als getrackter, retrybarer Job; ohne jobs synchron inline
+ *  (heutiges Verhalten). Capability-Detektion über `registry.getJob`, NICHT
+ *  `hasFeature` — deterministisch und ohne Toggle-Runtime-Abhängigkeit. */
+export async function enqueueProjectionRebuild(
+  projection: string,
+  deps: EnqueueProjectionRebuildDeps,
+): Promise<EnqueueProjectionRebuildResult> {
+  const { db, registry, jobRunner } = deps;
+  if (jobRunner !== undefined && registry.getJob(PROJECTION_REBUILD_JOB) !== undefined) {
+    const bullJobId = await jobRunner.dispatch(PROJECTION_REBUILD_JOB, { projection });
+    return { mode: "dispatched", bullJobId };
+  }
+  const result = await rebuildProjection(projection, { db, registry });
+  return { mode: "inline", result };
+}

package/src/pipeline/dispatcher.ts

@@ -278,7 +278,11 @@ export function createDispatcher(
     // Mirror notify: only built when the config feature wired its factory.
     const config =
       context._configAccessorFactory && db
-        ? context._configAccessorFactory({ user: { id: user.id, tenantId: user.tenantId }, db })
+        ? context._configAccessorFactory({
+            user: { id: user.id, tenantId: user.tenantId },
+            db,
+            secrets: context.secrets,
+          })
         : undefined;
 
     // Observability — feature-bound metrics handle, so ctx.metrics.inc("foo")
@@ -1382,7 +1386,11 @@ export function createDispatcher(
     }
     const db = createTenantDb(dbSource, user.tenantId, "tenant", context.tracer, context.meter);
     const configAccessor = context._configAccessorFactory
-      ? context._configAccessorFactory({ user: { id: user.id, tenantId: user.tenantId }, db })
+      ? context._configAccessorFactory({
+          user: { id: user.id, tenantId: user.tenantId },
+          db,
+          secrets: context.secrets,
+        })
       : undefined;
     return {
       db,