@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/feature-toggles/compose-tier-resolver.ts

@@ -0,0 +1,134 @@
+import {
+  type EffectiveFeaturesResolver,
+  isToggleableFeature,
+  type Registry,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { GlobalFeatureToggleRuntime } from "./toggle-runtime.js";
+
+// Composes a tenantTierResolver (tier-engine) with a GlobalFeatureToggleRuntime
+// (feature-toggles) into a single resolver an app can pass as
+// runProdApp/runDevApp's `effectiveFeatures`.
+//
+// The framework only auto-wires ONE tenantTierResolver plugin (single-plugin
+// assumption, see tier-resolver-extension.ts) — an app running BOTH
+// tier-engine (per-tenant feature cuts) and feature-toggles (global runtime
+// switches, e.g. an operator kill-switch not tied to any tier) needs to
+// combine them itself. This is that combination, factored out here instead
+// of duplicated per app.
+//
+// Two disjoint classes of toggleable feature exist once both are mounted:
+//   - tier-managed (e.g. a Team-tier perk like personal-access-tokens): the
+//     TIER decides membership, not the feature's own default — a toggleable
+//     feature with no override row must stay governed by its tier, or every
+//     tier-gated toggleable would silently leak/vanish the moment
+//     feature-toggles is composed in. The global layer may only NARROW this
+//     (`enabled: false` removes it; no row / `true` leaves the tier's grant
+//     untouched).
+//   - tier-unaware (e.g. a pure operator kill-switch with no tier
+//     differentiation at all, such as auth-self-registration): no tier's
+//     `features` list ever mentions it, so it would never appear in ANY
+//     tenant's tier-set — narrowing alone can only remove features, never
+//     grant this one. Its membership must come from computeEffectiveFeatures'
+//     normal cascade (override ?? toggleableDefault) instead.
+//
+// `tierResolver(SYSTEM_TENANT_ID)` is tier-engine's documented convention for
+// "union of every tier's features" (operator-tooling/async-dispatch
+// convention) — used here purely to classify which toggleable names are
+// tier-managed, without needing the app's TierMap as a separate parameter.
+export function composeTierResolverWithGlobalToggles(
+  tierResolver: EffectiveFeaturesResolver,
+  toggleRuntime: GlobalFeatureToggleRuntime,
+  // registry needed for toggleability lookups; toggleRuntime keeps its own registry reference private.
+  registry: Registry,
+): EffectiveFeaturesResolver {
+  // Lazy + memoized: computed on first composed(tenantId) call, not at
+  // compose-time. Late-bound holder wiring (e.g. run-dev-app.ts's tier
+  // resolver plugin) may not have its real tierResolver built yet when
+  // composeTierResolverWithGlobalToggles itself runs.
+  let tierManaged: ReadonlySet<string> | undefined;
+
+  const composed: EffectiveFeaturesResolver = (tenantId) => {
+    if (tierManaged === undefined) {
+      const managed = tierResolver(SYSTEM_TENANT_ID);
+      // fail-loud: an empty union means the resolver doesn't implement the SYSTEM_TENANT_ID convention at all.
+      if (managed.size === 0) {
+        throw new Error(
+          "composeTierResolverWithGlobalToggles: tierResolver(SYSTEM_TENANT_ID) " +
+            "returned an empty set. tier-engine's SYSTEM_TENANT_ID convention " +
+            "(union of every tier's features, plus always-on features) must " +
+            "never be empty — an empty result means the tierResolver passed in " +
+            "doesn't implement that convention, which would silently disable " +
+            "all tier-gating (every feature would be treated as tier-unaware).",
+        );
+      }
+      // Structural Rule 1: only the TOGGLEABLE subset of the union is tier-managed.
+      // Non-toggleable (always-on) names must keep reaching `result` through the
+      // globalCascade loop below even if this resolver's SYSTEM_TENANT_ID answer
+      // satisfies the emptiness guard above without also merging always-on into
+      // every per-tenant tierSet (framework#1528).
+      tierManaged = new Set(
+        [...managed].filter((name) => {
+          const feature = registry.getFeature(name);
+          return feature !== undefined && isToggleableFeature(feature);
+        }),
+      );
+    }
+
+    const tierSet = tierResolver(tenantId);
+    const result = new Set<string>();
+    for (const name of tierSet) {
+      // Only a toggleable feature's override can narrow the tier's grant —
+      // computeEffectiveFeatures' Rule 1 ignores overrides for features
+      // without a toggleableDefault, and an override row can otherwise
+      // reach a non-toggleable feature via seed-scripts/ops-SQL/an
+      // r.toggleable() removal after the fact (readOverride/refresh() have
+      // no toggleability gate of their own).
+      const feature = registry.getFeature(name);
+      const isToggleable = feature !== undefined && isToggleableFeature(feature);
+      if (!isToggleable || toggleRuntime.readOverride(name) !== false) {
+        result.add(name);
+      }
+    }
+    // toggleRuntime.effectiveFeatures() already applies computeEffectiveFeatures'
+    // full rule set (toggleableDefault ?? override, THEN the requires() cascade)
+    // — reusing it here instead of calling computeEffectiveFeatures directly
+    // keeps this in lockstep with the runtime's own dispatcher-facing callback.
+    const globalCascade = toggleRuntime.effectiveFeatures();
+    for (const name of globalCascade) {
+      if (!tierManaged.has(name)) result.add(name);
+    }
+
+    // requires() cascade over the combined result: a feature narrowed off by
+    // either loop above (tier-managed override, or absent from both sets)
+    // must also drop anything that itself requires it — computeEffectiveFeatures
+    // enforces this for its own single reader, but tierSet's membership isn't
+    // reader-driven, so the cascade has to be re-applied over the union.
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const name of [...result]) {
+        const feature = registry.getFeature(name);
+        if (!feature) {
+          result.delete(name);
+          changed = true;
+          continue;
+        }
+        for (const dep of feature.requires) {
+          if (!result.has(dep)) {
+            result.delete(name);
+            changed = true;
+            break;
+          }
+        }
+      }
+    }
+
+    return result;
+  };
+
+  if (tierResolver.trialGate) {
+    return Object.assign(composed, { trialGate: tierResolver.trialGate });
+  }
+  return composed;
+}

package/packages/bundled-features/src/feature-toggles/constants.ts

@@ -0,0 +1,40 @@
+// @runtime client
+export const FEATURE_TOGGLES_FEATURE = "feature-toggles" as const;
+
+// 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";
+
+// Shared acknowledgeCrossTenant() reason across all three handlers that read
+// or write globalFeatureStateTable — one string so the three call sites
+// can't drift (framework#2076).
+export const FEATURE_TOGGLE_CROSS_TENANT_REASON =
+  "global feature-toggle state, no tenant scope by design";
+
+// 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;
+
+export const FeatureToggleHandlers = {
+  set: "feature-toggles:write:set",
+} as const;
+
+export const FeatureToggleQueries = {
+  list: "feature-toggles:query:list",
+  registered: "feature-toggles:query:registered",
+} as const;
+
+export const TOGGLE_ADMIN_SCREEN_ID = "toggle-admin" as const;

package/packages/bundled-features/src/feature-toggles/events.ts

@@ -0,0 +1,18 @@
+import * as 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/packages/bundled-features/src/feature-toggles/feature.ts

@@ -0,0 +1,173 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  FEATURE_TOGGLE_SET_EVENT_NAME,
+  FeatureToggleHandlers,
+  FeatureToggleQueries,
+  TOGGLE_ADMIN_SCREEN_ID,
+} from "./constants.js";
+import { featureToggleSetSchema } from "./events.js";
+import { globalFeatureStateTableMeta } from "./global-feature-state-table.js";
+import { listQuery } from "./handlers/list.query.js";
+import { registeredQuery } from "./handlers/registered.query.js";
+import { createSetWriteHandler } from "./handlers/set.write.js";
+import { FEATURE_TOGGLES_I18N } from "./i18n.js";
+import type { GlobalFeatureToggleRuntime } from "./toggle-runtime.js";
+
+// 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().
+  //
+  // **Optional** — boot-mode (KUMIKO_DRY_RUN_ENV=boot) wires the feature
+  // up without ever calling the set-handler, so a runtime-stub is then
+  // pure cargo-cult. Omit `getRuntime` and the handler throws lazily on
+  // first call with an actionable message. App-authors who DO route to
+  // the set-handler at runtime MUST supply the accessor.
+  readonly getRuntime?: () => GlobalFeatureToggleRuntime;
+};
+
+export function createFeatureTogglesFeature(
+  options: FeatureTogglesOptions = {},
+): FeatureDefinition {
+  return defineFeature("feature-toggles", (r) => {
+    r.describe(
+      'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "shared"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
+    );
+    r.uiHints({
+      displayLabel: "Feature Toggles · Operator Switches",
+      category: "operations",
+      recommended: false,
+    });
+    r.systemScope();
+    r.storeTable(globalFeatureStateTableMeta, {
+      reason: "feature_toggles.global_override_snapshot",
+    });
+
+    // 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, { piiFields: "none" });
+
+    const handlers = {
+      set: r.writeHandler(createSetWriteHandler(options.getRuntime)),
+    };
+
+    const queries = {
+      list: r.queryHandler(listQuery),
+      registered: r.queryHandler(registeredQuery),
+    };
+
+    r.screen({
+      id: TOGGLE_ADMIN_SCREEN_ID,
+      type: "projectionList",
+      query: FeatureToggleQueries.registered,
+      columns: [
+        { field: "name", label: "feature-toggles.admin.col.feature" },
+        { field: "defaultLabel", label: "feature-toggles.admin.col.default" },
+        { field: "overrideLabel", label: "feature-toggles.admin.col.override" },
+        { field: "effectiveLabel", label: "feature-toggles.admin.col.effective" },
+      ],
+      rowActions: [
+        {
+          kind: "writeHandler",
+          id: "toggle",
+          label: "feature-toggles.admin.toggle",
+          handler: FeatureToggleHandlers.set,
+          payload: { map: { featureName: "name", enabled: "nextEnabled" } },
+          visible: { field: "toggleable", eq: true },
+        },
+      ],
+      access: { roles: ["SystemAdmin"] },
+    });
+    r.nav({
+      id: "toggle-admin",
+      label: "feature-toggles:nav.toggleAdmin",
+      screen: "feature-toggles:screen:toggle-admin",
+      order: 20,
+    });
+
+    r.translations({ keys: FEATURE_TOGGLES_I18N });
+
+    // toggle-cache-sync — multi-instance snapshot propagation. One shared
+    // cursor reads every toggle-set event once (fw#2625); the winning
+    // process's handler calls runtime.broadcastToggle, which publishes on
+    // GlobalFeatureToggleRuntime's syncSignal so every process (including
+    // the one that won the cursor) applies the flip to its own snapshot —
+    // see toggle-runtime.ts and toggle-sync-signal.ts. Without a syncSignal
+    // configured (no REDIS_URL — single-process dev/test), broadcastToggle
+    // applies directly; there is nobody else to reach. Named "cache-sync"
+    // (not "projection" or "audit") because it's side-effect-only
+    // infrastructure.
+    //
+    // 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 + Pub/Sub 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 via
+    //     initialize(); if another instance never ran the write, the MSP
+    //     + syncSignal is how it learns. All paths are idempotent — apply
+    //     is Map.set.
+    //
+    // startFrom: "now" — history is meaningless here, a flip is only ever
+    // relevant to processes already running when it happens.
+    //
+    // 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: "shared",
+      startFrom: "now",
+      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 }; // @cast-boundary engine-payload
+          if (!options.getRuntime) {
+            throw new Error(
+              "[feature-toggles] toggle-cache-sync MSP fired but createFeatureTogglesFeature " +
+                "was wired up without `getRuntime`. Wire the accessor in your app-config.",
+            );
+          }
+          options.getRuntime().broadcastToggle(payload.featureName, payload.enabled);
+        },
+      },
+    });
+
+    return { handlers, queries };
+  });
+}
+
+export { FEATURE_TOGGLE_SET_EVENT_NAME, FeatureToggleErrors } from "./constants.js";
+export {
+  globalFeatureStateTable,
+  globalFeatureStateTableMeta,
+} from "./global-feature-state-table.js";
+// Re-export the runtime factory + class so app-boot code has a single
+// import path: "@cosmicdrift/kumiko-bundled-features/feature-toggles".
+export {
+  createFeatureToggleRuntime,
+  GlobalFeatureToggleRuntime,
+  type ToggleSyncSignal,
+} from "./toggle-runtime.js";
+export { createRedisToggleSyncSignal, type RedisToggleSyncSignal } from "./toggle-sync-signal.js";

package/packages/bundled-features/src/feature-toggles/global-feature-state-table.ts

@@ -0,0 +1,47 @@
+import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  boolean,
+  declareGlobalTenancy,
+  type EntityTableMeta,
+  instant,
+  integer,
+  table as pgTable,
+  type SchemaTable,
+  sql,
+  text,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
+
+// 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: SchemaTable & TenancyBrand<"global"> = declareGlobalTenancy(
+  pgTable("store_global_feature_state", {
+    featureName: text("feature_name").primaryKey(),
+    enabled: boolean("enabled").notNull(),
+    // Optimistic-lock column: the set-handler updates `WHERE feature_name = ? AND
+    // version = ?`; a 0-row update means a concurrent write, so it 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"),
+  }),
+);
+
+// r.storeTable meta — without this, collectTableMetas(FEATURES) never
+// sees the table, so `kumiko schema generate` reports no changes and no
+// app ever gets a migration for it (framework gap, not app-local). Derived
+// from the pgTable above instead of hand-written a second time — the two
+// used to drift independently (framework#1529): a column added only to
+// the pgTable made queries type-check while the migration generator stayed
+// blind to it, failing in prod with "column ... does not exist" while every
+// mocked-stack test stayed green.
+export const globalFeatureStateTableMeta: EntityTableMeta = requireEntityTableMeta(
+  globalFeatureStateTable,
+  "globalFeatureStateTable",
+);

package/packages/bundled-features/src/feature-toggles/handlers/list.query.ts

@@ -0,0 +1,45 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { FEATURE_TOGGLE_CROSS_TENANT_REASON } from "../constants.js";
+import { globalFeatureStateTable } from "../global-feature-state-table.js";
+
+// 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",
+  description:
+    "Lists only the features that carry an explicit platform-wide on/off override, with who flipped it and when; use it to see which toggles were changed away from their default.",
+  schema: z.object({}),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (_event, ctx) => {
+    // ctx.systemDb is populated for r.systemScope() handlers only (feature.ts
+    // declares it) — guarded instead of asserted, see set.write.ts Guard 0.5.
+    if (!ctx.systemDb) {
+      throw new Error(
+        "[feature-toggles] list-query requires ctx.systemDb — the feature-toggles " +
+          "feature must stay r.systemScope() (see feature.ts).",
+      );
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(FEATURE_TOGGLE_CROSS_TENANT_REASON);
+
+    type Row = {
+      featureName: string;
+      enabled: boolean;
+      version: number;
+      updatedAt: Temporal.Instant;
+      updatedBy: string;
+    };
+    const rows = await db.global(globalFeatureStateTable).selectMany<Row>();
+    return {
+      items: rows.map((r) => ({
+        featureName: r.featureName,
+        enabled: r.enabled,
+        version: r.version,
+        updatedAt: r.updatedAt.toString(),
+        updatedBy: r.updatedBy,
+      })),
+    };
+  },
+});

package/packages/bundled-features/src/feature-toggles/handlers/registered.query.ts

@@ -0,0 +1,87 @@
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { FEATURE_TOGGLE_CROSS_TENANT_REASON } from "../constants.js";
+import { globalFeatureStateTable } from "../global-feature-state-table.js";
+
+// 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.
+
+function formatFlag(value: boolean | null): string {
+  if (value === null) return "inherit";
+  return value ? "on" : "off";
+}
+
+export const registeredQuery = defineQueryHandler({
+  name: "registered",
+  description:
+    "Lists every registered feature with whether it is toggleable, its default, its explicit override, its dependencies and its effective on/off state; use it as the full feature inventory.",
+  schema: z.object({}),
+  access: { roles: ["SystemAdmin"] },
+  handler: async (_event, ctx) => {
+    // ctx.systemDb is populated for r.systemScope() handlers only (feature.ts
+    // declares it) — guarded instead of asserted, see set.write.ts Guard 0.5.
+    if (!ctx.systemDb) {
+      throw new Error(
+        "[feature-toggles] registered-query requires ctx.systemDb — the feature-toggles " +
+          "feature must stay r.systemScope() (see feature.ts).",
+      );
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(FEATURE_TOGGLE_CROSS_TENANT_REASON);
+
+    type OverrideRow = { featureName: string; enabled: boolean };
+    const overrideRows = await db.global(globalFeatureStateTable).selectMany<OverrideRow>();
+    const overrides = new Map(overrideRows.map((r) => [r.featureName, r.enabled]));
+
+    // SystemAdmin operator-tooling: das listing soll die PLATTFORM-truth
+    // zeigen (alle features im Registry), nicht den eigenen tier-cut.
+    // Sprint-8a per-tenant signature → wir rufen mit SYSTEM_TENANT_ID,
+    // App-resolver returnt union-of-all-tier-features. Sentinel-Convention
+    // dokumentiert in DispatcherOptions.effectiveFeatures.
+    const effective = ctx.effectiveFeatures?.(SYSTEM_TENANT_ID);
+
+    const rows: Array<{
+      id: string;
+      name: string;
+      toggleable: boolean;
+      default: boolean | null;
+      override: boolean | null;
+      requires: readonly string[];
+      effective: boolean | null;
+      defaultLabel: string;
+      overrideLabel: string;
+      effectiveLabel: string;
+      nextEnabled: boolean;
+    }> = [];
+
+    for (const feature of ctx.registry.features.values()) {
+      const toggleable = feature.toggleableDefault !== undefined;
+      const override = overrides.get(feature.name);
+      const defaultValue = feature.toggleableDefault ?? null;
+      const effectiveValue = effective ? effective.has(feature.name) : null;
+      const effectiveBool = effectiveValue ?? defaultValue ?? false;
+
+      rows.push({
+        id: feature.name,
+        name: feature.name,
+        toggleable,
+        // Raw booleans for API consumers; label fields for projectionList columns.
+        default: defaultValue,
+        override: override ?? null,
+        requires: feature.requires,
+        effective: effectiveValue,
+        defaultLabel: formatFlag(defaultValue),
+        overrideLabel: formatFlag(override ?? null),
+        effectiveLabel: formatFlag(effectiveValue),
+        nextEnabled: !effectiveBool,
+      });
+    }
+
+    return { rows, nextCursor: null };
+  },
+});