@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/feature-toggles/constants.ts

@@ -0,0 +1,20 @@
+// Fully-qualified event name for feature-toggle changes. Kept as a constant
+// so write-handler + tests reference one source.
+export const FEATURE_TOGGLE_SET_EVENT_NAME = "feature-toggles:event:toggle-set";
+
+// Aggregate type for toggle-set events. Shares the feature name to keep the
+// events-table grep-friendly: every row belonging to this feature carries
+// "feature-toggles" in its aggregate_type column.
+export const FEATURE_TOGGLE_AGGREGATE_TYPE = "feature-toggles";
+
+// Error reasons surfaced from feature-toggle handlers. Scoped to the
+// feature's namespace per the framework's reason-convention.
+export const FeatureToggleErrors = {
+  // set-handler attempted to toggle a feature that didn't declare
+  // r.toggleable(). The dispatcher's gate ignores such features anyway,
+  // but writing a row for them would create the illusion of configurability.
+  notToggleable: "feature_not_toggleable",
+  // set-handler attempted to toggle a feature name that isn't registered.
+  // Prevents typos from silently piling up orphan rows.
+  unknownFeature: "unknown_feature",
+} as const;

package/src/feature-toggles/events.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+// Toggle-change event payload.
+//
+// Contract: every set-operation produces exactly one event, even when
+// enabled === previousEnabled. Redundant writes are legal (confirms the
+// current state, useful for ops "make sure feature X is on"), so consumers
+// that filter for actual transitions must compare enabled !== previousEnabled
+// themselves. `previousEnabled` is null when this is the first time the
+// feature is being toggled (no row existed).
+export const featureToggleSetSchema = z.object({
+  featureName: z.string().min(1),
+  enabled: z.boolean(),
+  previousEnabled: z.boolean().nullable(),
+  updatedBy: z.string(),
+});
+
+export type FeatureToggleSetPayload = z.infer<typeof featureToggleSetSchema>;

package/src/feature-toggles/feature.ts

@@ -0,0 +1,98 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { FEATURE_TOGGLE_SET_EVENT_NAME } from "./constants";
+import { featureToggleSetSchema } from "./events";
+import { listQuery } from "./handlers/list.query";
+import { registeredQuery } from "./handlers/registered.query";
+import { createSetWriteHandler } from "./handlers/set.write";
+import type { GlobalFeatureToggleRuntime } from "./toggle-runtime";
+
+// IMPORTANT: feature-toggles itself is NOT r.toggleable. Making it
+// toggleable would brick the system — once disabled, no handler of this
+// feature is reachable to turn it back on. The boot-validator won't catch
+// this (it only warns about dependency shapes), so the guarantee lives in
+// this file: do not add r.toggleable() here.
+
+export type FeatureTogglesOptions = {
+  // Accessor for the in-memory snapshot the dispatcher gate reads. Must
+  // return a resolved runtime by the time the feature's set-handler is
+  // called — NOT by the time the feature is registered. This matters
+  // because createFeatureToggleRuntime needs the registry that
+  // setupTestStack / buildServer builds from the feature list, so the
+  // runtime and the feature are chicken-and-egg at wire-up time. Passing
+  // an accessor (vs the runtime directly) lets the caller close over a
+  // mutable holder.
+  //
+  // Production setup: resolve the runtime after buildServer returns, then
+  // pass `() => runtime`. For tests, use createLateBoundHolder + .get().
+  readonly getRuntime: () => GlobalFeatureToggleRuntime;
+};
+
+export function createFeatureTogglesFeature(options: FeatureTogglesOptions): FeatureDefinition {
+  return defineFeature("feature-toggles", (r) => {
+    r.systemScope();
+
+    // Toggle-change domain event. The event ends up in the events-table
+    // alongside every other write — audit.list picks it up automatically,
+    // no dedicated projection needed. Qualified name after prefixing:
+    // "feature-toggles:event:toggle-set" (see constants.FEATURE_TOGGLE_SET_EVENT_NAME).
+    r.defineEvent("toggle-set", featureToggleSetSchema);
+
+    const handlers = {
+      set: r.writeHandler(createSetWriteHandler(options.getRuntime)),
+    };
+
+    const queries = {
+      list: r.queryHandler(listQuery),
+      registered: r.queryHandler(registeredQuery),
+    };
+
+    // toggle-cache-sync — multi-instance snapshot propagation. Every
+    // API/worker instance runs its own dispatcher cursor on this MSP
+    // (delivery: "per-instance") and converges its in-memory snapshot on
+    // every toggle-set event it observes. Named "cache-sync" (not
+    // "projection" or "audit") because it's side-effect-only
+    // infrastructure — the framework's boot-validator also rejects
+    // per-instance MSPs that carry a `table`.
+    //
+    // Why this is correct alongside the set-handler's own `runtime.apply`:
+    //   - local apply = immediate response-latency optimization so the
+    //     next request on the same instance sees the flip without a
+    //     dispatcher-tick round-trip
+    //   - MSP = multi-instance propagation + crash-recovery. If a process
+    //     crashes between appendEvent (persisted) and the local apply
+    //     (volatile), the MSP rebuilds the snapshot on restart; if
+    //     instance B never ran the write, the MSP is how it learns. Both
+    //     paths are idempotent — apply is Map.set, replay on boot just
+    //     converges to the DB state that initialize() already loaded.
+    //
+    // Requires: options.getRuntime() must resolve by the time the
+    // dispatcher processes its first toggle-set event. The holder-based
+    // wire-up (see FeatureTogglesOptions.getRuntime docstring) guarantees
+    // this in setupTestStack and production boot.
+    r.multiStreamProjection({
+      name: "toggle-cache-sync",
+      delivery: "per-instance",
+      apply: {
+        [FEATURE_TOGGLE_SET_EVENT_NAME]: async (event) => {
+          // The event payload shape is guaranteed by featureToggleSetSchema
+          // (validated on append). Shallow-cast to a typed shape rather
+          // than re-parsing — the payload round-trips through JSON and is
+          // fixed at the source.
+          const payload = event.payload as { featureName: string; enabled: boolean };
+          options.getRuntime().apply(payload.featureName, payload.enabled);
+        },
+      },
+    });
+
+    return { handlers, queries };
+  });
+}
+
+export { FEATURE_TOGGLE_SET_EVENT_NAME, FeatureToggleErrors } from "./constants";
+export { globalFeatureStateTable } from "./global-feature-state-table";
+// Re-export the runtime factory + class so app-boot code has a single
+// import path: "@cosmicdrift/kumiko-bundled-features/feature-toggles".
+export {
+  createFeatureToggleRuntime,
+  GlobalFeatureToggleRuntime,
+} from "./toggle-runtime";

package/src/feature-toggles/global-feature-state-table.ts

@@ -0,0 +1,28 @@
+import {
+  boolean,
+  instant,
+  integer,
+  table as pgTable,
+  text,
+} from "@cosmicdrift/kumiko-framework/db";
+import { sql } from "drizzle-orm";
+
+// Global feature-toggle override state. One row per feature that has ever
+// been explicitly flipped by an operator. Missing row = "no override,
+// fall back to the feature's r.toggleable({ default }) value".
+//
+// PK is featureName (text) — not a surrogate UUID — because the feature
+// name IS the identity here. No tenantId: this is a global override that
+// applies across every tenant (per-tenant toggles are intentionally out of
+// scope, see core-feature-toggles.md).
+export const globalFeatureStateTable = pgTable("read_global_feature_state", {
+  featureName: text("feature_name").primaryKey(),
+  enabled: boolean("enabled").notNull(),
+  // Optimistic-lock column. The set-handler reads the existing row, then
+  // updates with `WHERE feature_name = ? AND version = ?`; a 0-row update
+  // means someone else wrote concurrently — the handler retries the fetch.
+  version: integer("version").notNull().default(1),
+  updatedAt: instant("updated_at").default(sql`now()`).notNull(),
+  // UserId (text — SessionUser.id is a uuid string post-ES).
+  updatedBy: text("updated_by"),
+});

package/src/feature-toggles/handlers/list.query.ts

@@ -0,0 +1,26 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { globalFeatureStateTable } from "../global-feature-state-table";
+
+// List every row in the global_feature_state table — i.e. every feature
+// that has ever been explicitly flipped. Features without a row aren't
+// returned; callers must combine this with `registered` to see the full
+// effective state (registered features + their current override, if any).
+export const listQuery = defineQueryHandler({
+  name: "list",
+  schema: z.object({}),
+  access: { roles: ["SystemAdmin", "Admin"] },
+  handler: async (_event, ctx) => {
+    type Row = typeof globalFeatureStateTable.$inferSelect;
+    const rows = (await ctx.db.select().from(globalFeatureStateTable)) as Row[];
+    return {
+      items: rows.map((r) => ({
+        featureName: r.featureName,
+        enabled: r.enabled,
+        version: r.version,
+        updatedAt: r.updatedAt.toString(),
+        updatedBy: r.updatedBy,
+      })),
+    };
+  },
+});

package/src/feature-toggles/handlers/registered.query.ts

@@ -0,0 +1,56 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { globalFeatureStateTable } from "../global-feature-state-table";
+
+// Inventory of every registered feature, annotated with toggle metadata
+// and the current effective state. This is the canonical "what's here,
+// what's on, what depends on what" snapshot — the UI for the operator
+// toggle screen binds to it.
+//
+// Design: registry introspection (toggleable/default/requires) + a single
+// DB read of overrides. No per-feature DB calls. Scales to however many
+// features an app registers — currently tens, never thousands.
+export const registeredQuery = defineQueryHandler({
+  name: "registered",
+  schema: z.object({}),
+  access: { roles: ["SystemAdmin", "Admin"] },
+  handler: async (_event, ctx) => {
+    type OverrideRow = Pick<typeof globalFeatureStateTable.$inferSelect, "featureName" | "enabled">;
+    const overrideRows = (await ctx.db
+      .select({
+        featureName: globalFeatureStateTable.featureName,
+        enabled: globalFeatureStateTable.enabled,
+      })
+      .from(globalFeatureStateTable)) as OverrideRow[];
+    const overrides = new Map(overrideRows.map((r) => [r.featureName, r.enabled]));
+
+    const effective = ctx.effectiveFeatures?.();
+
+    const items = [];
+    for (const feature of ctx.registry.features.values()) {
+      const toggleable = feature.toggleableDefault !== undefined;
+      const override = overrides.get(feature.name);
+      items.push({
+        name: feature.name,
+        toggleable,
+        // `default` is null when non-toggleable; the UI must render
+        // non-toggleable features as "always on" without an enable/disable
+        // control (flipping them would be rejected by the set-handler).
+        default: feature.toggleableDefault ?? null,
+        // `override` is null when no explicit row exists. That's distinct
+        // from "override says on" or "override says off" so the UI can show
+        // an "inherits default" indicator.
+        override: override ?? null,
+        requires: feature.requires,
+        // Effective = what the dispatcher-gate actually uses right now,
+        // after cascade. When the feature-toggles runtime isn't wired
+        // (dev setup without the feature loaded), we surface null so the
+        // UI knows the runtime isn't available rather than defaulting
+        // to "everything on".
+        effective: effective ? effective.has(feature.name) : null,
+      });
+    }
+
+    return { items };
+  },
+});

package/src/feature-toggles/handlers/set.write.ts

@@ -0,0 +1,158 @@
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+import {
+  UnprocessableError,
+  VersionConflictError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { and, eq, sql } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import {
+  FEATURE_TOGGLE_AGGREGATE_TYPE,
+  FEATURE_TOGGLE_SET_EVENT_NAME,
+  FeatureToggleErrors,
+} from "../constants";
+import { globalFeatureStateTable } from "../global-feature-state-table";
+import type { GlobalFeatureToggleRuntime } from "../toggle-runtime";
+
+// Factory: binds a runtime accessor to the handler at registration time.
+// The runtime holds the in-memory snapshot that the dispatcher's gate
+// reads; every successful set() call must update it, otherwise the flip
+// won't take effect until the next boot.
+//
+// Accessor form (instead of direct runtime ref) supports the bootstrapping
+// flow: tests + setupTestStack construct the feature definition BEFORE the
+// runtime exists (the runtime needs the registry, which setupTestStack
+// builds from the features). The accessor is resolved lazily, at call time.
+export function createSetWriteHandler(getRuntime: () => GlobalFeatureToggleRuntime) {
+  return defineWriteHandler({
+    name: "set",
+    schema: z.object({
+      featureName: z.string().min(1),
+      enabled: z.boolean(),
+    }),
+    // Platform-operator action — SystemAdmin only.
+    access: { roles: ["SystemAdmin"] },
+    handler: async (event, ctx) => {
+      const { featureName, enabled } = event.payload;
+
+      // Guard 1: featureName must be a registered feature. Otherwise we'd
+      // pile up orphan rows from typos that the gate would silently apply
+      // (if someone ever added a feature with that name later).
+      const feature = ctx.registry.getFeature(featureName);
+      if (!feature) {
+        return writeFailure(
+          new UnprocessableError(FeatureToggleErrors.unknownFeature, {
+            i18nKey: "feature-toggles.errors.unknownFeature",
+            details: { featureName },
+          }),
+        );
+      }
+
+      // Guard 2: feature must be toggleable. Non-toggleable features (auth,
+      // tenant, user, feature-toggles itself) must stay on — the gate
+      // would ignore any row, but writing one sends the wrong signal to
+      // anyone reading the table.
+      if (feature.toggleableDefault === undefined) {
+        return writeFailure(
+          new UnprocessableError(FeatureToggleErrors.notToggleable, {
+            i18nKey: "feature-toggles.errors.notToggleable",
+            details: { featureName },
+          }),
+        );
+      }
+
+      // Read current state for event payload + optimistic-lock version.
+      // `$inferSelect` narrows the result shape to the real table schema —
+      // no hand-rolled cast, no drift if a column is added later.
+      type StateRow = typeof globalFeatureStateTable.$inferSelect;
+      const [existing] = (await ctx.db
+        .select()
+        .from(globalFeatureStateTable)
+        .where(eq(globalFeatureStateTable.featureName, featureName))
+        .limit(1)) as StateRow[];
+
+      const previousEnabled = existing?.enabled ?? null;
+
+      if (!existing) {
+        // First-time override: insert.
+        await ctx.db.insert(globalFeatureStateTable).values({
+          featureName,
+          enabled,
+          version: 1,
+          updatedBy: event.user.id,
+          updatedAt: Temporal.Now.instant(),
+        });
+      } else {
+        // Upsert with optimistic lock. Two operators flipping the same
+        // toggle simultaneously is rare but possible — the version-WHERE
+        // ensures only one wins; the loser sees VersionConflictError.
+        const updated = await ctx.db
+          .update(globalFeatureStateTable)
+          .set({
+            enabled,
+            version: sql<number>`${globalFeatureStateTable.version} + 1`,
+            updatedBy: event.user.id,
+            updatedAt: Temporal.Now.instant(),
+          })
+          .where(
+            and(
+              eq(globalFeatureStateTable.featureName, featureName),
+              eq(globalFeatureStateTable.version, existing.version),
+            ),
+          )
+          .returning();
+
+        if (updated.length === 0) {
+          return writeFailure(
+            new VersionConflictError({
+              entityId: featureName,
+              expectedVersion: existing.version,
+              currentVersion: existing.version + 1,
+            }),
+          );
+        }
+      }
+
+      // Domain event — the event-store IS the toggle-change audit trail.
+      // aggregateId = SYSTEM_TENANT_ID (uuid) because the events table
+      // types aggregate_id as uuid. Per-feature stream isolation would
+      // need synthetic UUIDs from the feature-name, which add nothing
+      // audit-wise; one shared toggle-changes stream per system is fine,
+      // and filtering by payload.featureName is trivial at query time.
+      // This mirrors how `config` handles the same constraint for
+      // its config-changed events.
+      // appendEventUnsafe — bundled-features ohne lokalen Wrapper. Apps
+      // mit `yarn kumiko codegen` kriegen `.kumiko/define.ts` als strict-
+      // path; bundled-features bleibt bei der unsafe-Variante. Schema-
+      // Validation läuft trotzdem via r.defineEvent("toggle-set", ...).
+      await ctx.appendEventUnsafe({
+        aggregateId: SYSTEM_TENANT_ID,
+        aggregateType: FEATURE_TOGGLE_AGGREGATE_TYPE,
+        type: FEATURE_TOGGLE_SET_EVENT_NAME,
+        payload: {
+          featureName,
+          enabled,
+          previousEnabled,
+          updatedBy: event.user.id,
+        },
+      });
+
+      // Update the local in-memory snapshot. Done AFTER the DB write +
+      // event append so a crash in either leaves the snapshot consistent
+      // with what's persisted. This is the response-latency optimization:
+      // the next request on THIS instance sees the flip without waiting
+      // for a dispatcher tick. Other instances learn the change through
+      // the `toggle-cache-sync` MSP (see feature-toggles-feature.ts). Both
+      // paths are idempotent — Map.set is last-write-wins and the DB is
+      // the source of truth after boot-time initialize().
+      getRuntime().apply(featureName, enabled);
+
+      return {
+        isSuccess: true,
+        data: { featureName, enabled, previousEnabled },
+      };
+    },
+  });
+}

package/src/feature-toggles/index.ts

@@ -0,0 +1,9 @@
+export {
+  createFeatureToggleRuntime,
+  createFeatureTogglesFeature,
+  FEATURE_TOGGLE_SET_EVENT_NAME,
+  FeatureToggleErrors,
+  type FeatureTogglesOptions,
+  GlobalFeatureToggleRuntime,
+  globalFeatureStateTable,
+} from "./feature";

package/src/feature-toggles/toggle-runtime.ts

@@ -0,0 +1,73 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  computeEffectiveFeatures,
+  type Registry,
+  type ToggleReader,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { globalFeatureStateTable } from "./global-feature-state-table";
+
+// Holds the current global-override snapshot in memory and exposes a
+// synchronous reader — the dispatcher's feature-gate calls it on every
+// handler invocation, so this must not do I/O on the hot path. The
+// snapshot is loaded once at boot via `.initialize()`, refreshed by the
+// set-handler on the local instance, and kept in sync across
+// instances by the `toggle-cache-sync` MSP (declared on the
+// feature-toggles feature, delivery: "per-instance"). Every API/worker
+// process observes every toggle-set event and applies it to its local
+// snapshot — no Redis / SSE / polling needed; the existing events-table
+// + event-dispatcher pipeline handles propagation.
+export class GlobalFeatureToggleRuntime {
+  private snapshot = new Map<string, boolean>();
+
+  constructor(
+    private readonly db: DbConnection,
+    private readonly registry: Registry,
+  ) {}
+
+  async initialize(): Promise<void> {
+    const rows = await this.db
+      .select({
+        featureName: globalFeatureStateTable.featureName,
+        enabled: globalFeatureStateTable.enabled,
+      })
+      .from(globalFeatureStateTable);
+    this.snapshot = new Map(rows.map((r) => [r.featureName, r.enabled]));
+  }
+
+  // Re-read the full snapshot. Called from the set-handler after a
+  // successful write — cheap point-update would be an optimisation but
+  // the table is small (O(features)) and this keeps the cache honest in
+  // the presence of concurrent external writes (seed scripts, ops SQL).
+  async refresh(): Promise<void> {
+    await this.initialize();
+  }
+
+  // In-memory cache update. Used by the set-handler when a single
+  // featureName transitions — saves a round-trip compared to refresh()
+  // while staying correct because set-handlers serialise via optimistic
+  // lock. Kept alongside refresh() so both options are explicit.
+  apply(featureName: string, enabled: boolean): void {
+    this.snapshot.set(featureName, enabled);
+  }
+
+  // The callback shape the dispatcher expects. Computes the effective
+  // feature set from the current snapshot + the registry's requires()
+  // cascade every call. Cheap: the cascade is a DFS over O(features);
+  // for the expected sizes (tens of features per app) this is ~µs.
+  effectiveFeatures = (): ReadonlySet<string> => {
+    const reader: ToggleReader = (name) => this.snapshot.get(name);
+    return computeEffectiveFeatures(this.registry, reader);
+  };
+}
+
+// Factory for app-boot wiring: instantiate, initialize, return both the
+// runtime (for the set-handler to refresh) and the callback (for
+// createDispatcher's effectiveFeatures option).
+export async function createFeatureToggleRuntime(
+  db: DbConnection,
+  registry: Registry,
+): Promise<GlobalFeatureToggleRuntime> {
+  const runtime = new GlobalFeatureToggleRuntime(db, registry);
+  await runtime.initialize();
+  return runtime;
+}

package/src/file-foundation/__tests__/feature.test.ts

@@ -0,0 +1,35 @@
+// feature.ts contract tests — pin the public surface of the
+// Plugin-API-shaped file-foundation. Provider-specific configs/secrets
+// are tested in their own provider-feature (file-provider-s3/__tests__).
+
+import { describe, expect, test } from "vitest";
+import { fileFoundationFeature } from "../feature";
+
+describe("fileFoundationFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(fileFoundationFeature.name).toBe("file-foundation");
+  });
+
+  test("declares config as a hard requirement (provider-selector lives there)", () => {
+    expect(fileFoundationFeature.requires).toContain("config");
+  });
+
+  test("does NOT require secrets — provider-plugins own their own secrets", () => {
+    expect(fileFoundationFeature.requires).not.toContain("secrets");
+  });
+});
+
+describe("fileFoundationFeature.exports — typed handles", () => {
+  test("exposes only the provider-selector config-key", () => {
+    const keys = fileFoundationFeature.exports.configKeys;
+    expect(keys.provider).toBeDefined();
+    expect((keys as Record<string, unknown>)["bucket"]).toBeUndefined();
+    expect((keys as Record<string, unknown>)["region"]).toBeUndefined();
+  });
+});
+
+describe("fileFoundationFeature — registers extension-point", () => {
+  test("declares the 'fileProvider' extension-point", () => {
+    expect(fileFoundationFeature.registrarExtensions["fileProvider"]).toBeDefined();
+  });
+});