@cosmicdrift/kumiko-framework 0.27.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.27.0",
+  "version": "0.31.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>",

package/src/api/auth-routes.ts

@@ -115,6 +115,10 @@ type MembershipRow = {
   userId: string;
   tenantId: TenantId;
   roles: string[];
+  /** Display-Name des Tenants — liefert die membershipQuery seit dem
+   *  tenant-switcher-Fix mit; optional für ältere App-eigene Queries. */
+  tenantName?: string;
+  tenantKey?: string;
 };
 
 // Guest identity used for unauthenticated calls (e.g. login). The "all" role
@@ -754,6 +758,8 @@ export function createAuthRoutes(
         tenants: memberships.map((m) => ({
           tenantId: m.tenantId,
           roles: m.roles,
+          ...(m.tenantName !== undefined && { name: m.tenantName }),
+          ...(m.tenantKey !== undefined && { key: m.tenantKey }),
         })),
         activeTenantId: user.tenantId,
       });

package/src/api/server.ts

@@ -23,7 +23,7 @@ import {
   wrapRedisClient,
 } from "../observability";
 import type { DispatcherOptions } from "../pipeline/dispatcher";
-import { createDispatcher } from "../pipeline/dispatcher";
+import { createDispatcher, type Dispatcher } from "../pipeline/dispatcher";
 import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state";
 import type { EventDedup } from "../pipeline/event-dedup";
 import type { EventConsumer, EventDispatcher } from "../pipeline/event-dispatcher";
@@ -195,6 +195,11 @@ export type KumikoServer = {
   jwt: JwtHelper;
   sseBroker: SseBroker;
   observability: ObservabilityProvider;
+  // The command-dispatcher behind /api/* — same idempotency/jobRunner/
+  // lifecycle wiring as HTTP-dispatched writes. For dispatching outside
+  // the HTTP pipeline, e.g. provider-webhook routes that authenticate
+  // via signature instead of JWT (subscription-stripe et al.).
+  dispatcher: Dispatcher;
   // Present when at least one consumer is wired and context.db is a
   // DbConnection. Caller owns the lifecycle: `.start()` in boot, `.stop()`
   // in shutdown. Tests drain via `.runOnce()` instead.
@@ -619,6 +624,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     jwt,
     sseBroker,
     observability,
+    dispatcher,
     ...(eventDispatcher ? { eventDispatcher } : {}),
     ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
   };

package/src/bun-db/index.ts

@@ -9,14 +9,16 @@ export type {
   PgListenClient,
 } from "./connection";
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection";
-export type { SelectOptions, WhereObject, WhereOperator, WhereValue } from "./query";
+export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query";
 export {
+  asEntityTableMeta,
   asRawClient,
   countWhere,
   type DeleteManyBatchedOptions,
   type DeleteManyBatchedResult,
   deleteMany,
   deleteManyBatched,
+  extractTableInfo,
   fetchOne,
   type IncrementCounterOptions,
   incrementCounter,

package/src/bun-db/query.ts

@@ -60,7 +60,7 @@ function isEntityTableMeta(v: unknown): v is EntityTableMeta {
 //    to a column-handle shadowing a meta key.
 //  - buildEntityTableMeta / defineUnmanagedTable return a plain meta with no
 //    handle-spread, so its structural shape is itself unshadowable.
-function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
+export function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
   if (table === null || typeof table !== "object") return undefined;
   const fromSymbol = (table as Record<symbol, unknown>)[KUMIKO_META_SYMBOL];
   if (isEntityTableMeta(fromSymbol)) return fromSymbol;

package/src/db/__tests__/collect-table-metas.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { collectTableMetas } from "../collect-table-metas";
+import { integer, type SchemaTable, table, text, uuid } from "../dialect";
+import { defineUnmanagedTable } from "../entity-table-meta";
+import { buildEntityTable } from "../table-builder";
+
+function exampleEntity() {
+  return createEntity({
+    table: "read_units",
+    fields: { name: createTextField() },
+  });
+}
+
+const counterTable = table("read_unit_counters", {
+  id: uuid("id").primaryKey(),
+  count: integer("count").notNull().default(0),
+}) as unknown as SchemaTable;
+
+describe("collectTableMetas (#255)", () => {
+  test("collects entity, projection, MSP and rawTable tables — same sources as the test-stack auto-push", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection({
+        name: "unit-counters",
+        source: "unit",
+        table: counterTable,
+        apply: {},
+      });
+      r.multiStreamProjection({
+        name: "unit-audit",
+        table: table("read_unit_audit", {
+          id: uuid("id").primaryKey(),
+          detail: text("detail"),
+        }) as unknown as SchemaTable,
+        apply: { "unit.created": async () => {} },
+      });
+      // side-effect-only MSP — no table, must be skipped without throwing
+      r.multiStreamProjection({ name: "unit-notify", apply: { "unit.created": async () => {} } });
+      r.rawTable(
+        "cache",
+        table("unit_cache", {
+          id: uuid("id").primaryKey(),
+        }) as unknown as SchemaTable,
+        { reason: "test fixture" },
+      );
+      r.unmanagedTable(
+        defineUnmanagedTable({
+          tableName: "read_unit_log",
+          columns: [{ name: "id", pgType: "serial", notNull: true, primaryKey: true }],
+        }),
+        { reason: "test fixture" },
+      );
+    });
+
+    const names = collectTableMetas([feature]).map((m) => m.tableName);
+    expect(names).toContain("read_units"); // entity
+    expect(names).toContain("read_unit_counters"); // r.projection
+    expect(names).toContain("read_unit_audit"); // r.multiStreamProjection
+    expect(names).toContain("unit_cache"); // r.rawTable
+    expect(names).toContain("read_unit_log"); // r.unmanagedTable
+    expect(names).toHaveLength(5);
+  });
+
+  test("dedupes a projection that materializes into an entity table — entity meta wins", () => {
+    const entity = exampleEntity();
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", entity);
+      r.projection({
+        name: "unit-alt",
+        source: "unit",
+        table: buildEntityTable("unit", entity) as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+
+    const metas = collectTableMetas([feature]);
+    expect(metas.filter((m) => m.tableName === "read_units")).toHaveLength(1);
+  });
+
+  test("throws when two table-bearing registrations declare the same table with diverging columns", () => {
+    const a = defineFeature("feat-a", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection({
+        name: "conflict-a",
+        source: "unit",
+        table: table("read_conflict", {
+          id: uuid("id").primaryKey(),
+          count: integer("count").notNull(),
+        }) as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+    const b = defineFeature("feat-b", (r) => {
+      r.entity("thing", exampleEntity());
+      r.projection({
+        name: "conflict-b",
+        source: "thing",
+        table: table("read_conflict", {
+          id: uuid("id").primaryKey(),
+          label: text("label").notNull(),
+        }) as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+
+    expect(() => collectTableMetas([a, b])).toThrow(/read_conflict.*diverging/);
+  });
+
+  test("throws when a projection table carries no EntityTableMeta", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection({
+        name: "broken",
+        source: "unit",
+        // System-Grenze: absichtlich kaputtes table-Objekt — der Cast
+        // simuliert eine fremd-konstruierte Tabelle ohne kumiko-Meta.
+        table: { tableName: "read_broken" } as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+
+    expect(() => collectTableMetas([feature])).toThrow(/no EntityTableMeta/);
+  });
+});

package/src/db/collect-table-metas.ts

@@ -0,0 +1,81 @@
+// collectTableMetas — kanonische ENTITY_METAS-Quelle für `kumiko schema
+// generate`. Erfasst dieselben Tabellen-Quellen wie der setupTestStack-
+// auto-push (entities, unmanagedTables, projections, multiStreamProjections,
+// rawTables) — die frühere Template-Variante sammelte nur entities +
+// unmanagedTables, wodurch projection-only-Tabellen (z.B. billing-foundation
+// read_subscriptions) nie in Migrations landeten und der erste Prod-Write
+// crashte (#255).
+
+import { asEntityTableMeta } from "../bun-db/query";
+import type { FeatureDefinition } from "../engine/types";
+import { buildEntityTableMeta, type EntityTableMeta } from "./entity-table-meta";
+import { enumerateFeatureTableSources } from "./feature-table-sources";
+
+function canonicalColumnsKey(meta: EntityTableMeta): string {
+  // Spalten-Identität unabhängig von Deklarations-Reihenfolge und
+  // Objekt-Key-Order. Indexes bleiben außen vor: eine Projection-Table
+  // (buildEntityTable ohne relations) trägt legitim weniger FK-Indexes
+  // als das Entity-Meta derselben Tabelle.
+  return [...meta.columns]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (c) =>
+        `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`,
+    )
+    .join("\n");
+}
+
+export function collectTableMetas(
+  features: readonly FeatureDefinition[],
+): readonly EntityTableMeta[] {
+  const metas: EntityTableMeta[] = [];
+  const byName = new Map<string, { meta: EntityTableMeta; origin: string }>();
+
+  // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
+  // Verhalten (gleiche Reihenfolge, gleiche buildEntityTableMeta-Optionen).
+  for (const feature of features) {
+    for (const [name, ent] of Object.entries(feature.entities)) {
+      const meta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
+      metas.push(meta);
+      byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
+    }
+    for (const entry of Object.values(feature.unmanagedTables)) {
+      metas.push(entry.meta);
+      byName.set(entry.meta.tableName, {
+        meta: entry.meta,
+        origin: `unmanagedTable "${entry.name}" (${feature.name})`,
+      });
+    }
+  }
+
+  // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-
+  // Tabelle aus Feature B gegen eine gleichnamige Projection-Table aus
+  // Feature A gewinnt — Entity-Metas sind die reichere Quelle (FK-Indexes
+  // aus relations).
+  for (const feature of features) {
+    for (const { table, origin } of enumerateFeatureTableSources(feature)) {
+      const meta = asEntityTableMeta(table);
+      if (!meta) {
+        throw new Error(
+          `collectTableMetas: ${origin} carries no EntityTableMeta — ` +
+            "build the table via table() / buildEntityTable / defineUnmanagedTable.",
+        );
+      }
+      const existing = byName.get(meta.tableName);
+      if (existing) {
+        if (canonicalColumnsKey(existing.meta) !== canonicalColumnsKey(meta)) {
+          throw new Error(
+            `collectTableMetas: table "${meta.tableName}" is declared with diverging ` +
+              `columns by ${origin} and ${existing.origin}. Align the column ` +
+              "definitions or rename one of the tables.",
+          );
+        }
+        continue;
+      }
+      metas.push(meta);
+      byName.set(meta.tableName, { meta, origin });
+    }
+  }
+
+  return metas;
+}

package/src/db/feature-table-sources.ts

@@ -0,0 +1,35 @@
+// Single enumeration of every table-bearing registration on a feature
+// (r.projection, r.multiStreamProjection with table, r.rawTable). Consumed
+// by BOTH the setupTestStack auto-push and collectTableMetas — one list, so
+// test-DB-push and `kumiko schema generate` cannot drift apart again (#255).
+// A new table-bearing registrar must be added HERE, not in the consumers.
+
+import type { FeatureDefinition } from "../engine/types";
+
+export type FeatureTableSource = {
+  readonly table: unknown;
+  // Stable human-readable label, unique across features — used as push-key
+  // and in error messages.
+  readonly origin: string;
+};
+
+export function enumerateFeatureTableSources(
+  feature: FeatureDefinition,
+): readonly FeatureTableSource[] {
+  const sources: FeatureTableSource[] = [];
+  for (const [name, proj] of Object.entries(feature.projections)) {
+    sources.push({ table: proj.table, origin: `projection "${name}" (${feature.name})` });
+  }
+  for (const [name, msp] of Object.entries(feature.multiStreamProjections)) {
+    // table omitted = side-effect-only MSP, materialises nothing.
+    if (!msp.table) continue;
+    sources.push({
+      table: msp.table,
+      origin: `multiStreamProjection "${name}" (${feature.name})`,
+    });
+  }
+  for (const [name, raw] of Object.entries(feature.rawTables)) {
+    sources.push({ table: raw.table, origin: `rawTable "${name}" (${feature.name})` });
+  }
+  return sources;
+}

package/src/db/index.ts

@@ -1,4 +1,5 @@
 export { assertExistsIn } from "./assert-exists-in";
+export { collectTableMetas } from "./collect-table-metas";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 export { seedConfigValues } from "./config-seed";
 export type { DbConnection, DbConnectionOptions, DbRow, DbRunner, DbTx } from "./connection";
@@ -50,6 +51,10 @@ export type {
   EventStoreExecutorOptions,
 } from "./event-store-executor";
 export { createEventStoreExecutor, entityEventName } from "./event-store-executor";
+export {
+  enumerateFeatureTableSources,
+  type FeatureTableSource,
+} from "./feature-table-sources";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp";
 export {
   diffSnapshots,

package/src/engine/__tests__/engine.test.ts

@@ -23,6 +23,35 @@ describe("defineFeature", () => {
     expect(feature.name).toBe("test");
   });
 
+  test("r.describe() flows into the definition, trimmed", () => {
+    const feature = defineFeature("test", (r) => {
+      r.describe("  Stores per-tenant widgets.  ");
+    });
+    expect(feature.description).toBe("Stores per-tenant widgets.");
+  });
+
+  test("description is absent when r.describe() is not called", () => {
+    const feature = defineFeature("test", () => {});
+    expect("description" in feature).toBe(false);
+  });
+
+  test("r.describe() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.describe("first");
+        r.describe("second");
+      }),
+    ).toThrow(/r\.describe\(\) called twice/);
+  });
+
+  test("r.describe() throws on empty or whitespace-only text", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.describe("   ");
+      }),
+    ).toThrow(/non-empty string/);
+  });
+
   test("collects entities", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

package/src/engine/__tests__/registry.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { createTenantConfig } from "../config-helpers";
+import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
 import type { FeatureDefinition } from "../types/feature";
 
@@ -56,3 +58,76 @@ describe("createRegistry slot robustness", () => {
     ).not.toThrow();
   });
 });
+
+describe("extensionSelector boot-validation", () => {
+  function foundationFeature() {
+    return defineFeature("probe-foundation", (r) => {
+      r.extendsRegistrar("probeTransport", { onRegister: () => undefined });
+      const configKeys = r.config({
+        keys: { provider: createTenantConfig("text", { default: "" }) },
+      });
+      r.extensionSelector("probeTransport", configKeys.provider);
+      return { configKeys };
+    });
+  }
+
+  test("valid declaration lands in getAllExtensionSelectors", () => {
+    const registry = createRegistry([foundationFeature()]);
+    expect(registry.getAllExtensionSelectors().get("probeTransport")).toBe(
+      "probe-foundation:config:provider",
+    );
+  });
+
+  test("usages carry the owning featureName after merge", () => {
+    const provider = defineFeature("probe-smtp", (r) => {
+      r.useExtension("probeTransport", "smtp");
+    });
+    const registry = createRegistry([foundationFeature(), provider]);
+    const usage = registry.getExtensionUsages("probeTransport")[0];
+    expect(usage?.featureName).toBe("probe-smtp");
+  });
+
+  test("duplicate selector across features fails the boot", () => {
+    const rival = defineFeature("probe-rival", (r) => {
+      const configKeys = r.config({
+        keys: { provider: createTenantConfig("text", { default: "" }) },
+      });
+      r.extensionSelector("probeTransport", configKeys.provider);
+      return { configKeys };
+    });
+    expect(() => createRegistry([foundationFeature(), rival])).toThrow(
+      /Duplicate extension selector/,
+    );
+  });
+
+  test("selector for an undeclared extension fails the boot", () => {
+    const orphan = defineFeature("probe-orphan", (r) => {
+      const configKeys = r.config({
+        keys: { provider: createTenantConfig("text", { default: "" }) },
+      });
+      r.extensionSelector("ghostTransport", configKeys.provider);
+      return { configKeys };
+    });
+    expect(() => createRegistry([orphan])).toThrow(/no feature registers that extension/);
+  });
+
+  test("selector pointing at an unknown config key fails the boot", () => {
+    const typo = defineFeature("probe-typo", (r) => {
+      r.extendsRegistrar("probeTransport", { onRegister: () => undefined });
+      r.extensionSelector("probeTransport", "probe-typo:config:does-not-exist");
+    });
+    expect(() => createRegistry([typo])).toThrow(/unknown config key/);
+  });
+
+  test("declaring the selector twice in one feature fails at define-time", () => {
+    expect(() =>
+      defineFeature("probe-double", (r) => {
+        const configKeys = r.config({
+          keys: { provider: createTenantConfig("text", { default: "" }) },
+        });
+        r.extensionSelector("probeTransport", configKeys.provider);
+        r.extensionSelector("probeTransport", configKeys.provider);
+      }),
+    ).toThrow(/declared twice/);
+  });
+});

package/src/engine/config-helpers.ts

@@ -49,6 +49,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
   bounds?: T extends "number" ? ConfigBounds : never;
   computed?: ConfigComputedFn<T>;
   allowPerRequest?: T extends "text" ? never : boolean;
+  required?: boolean;
 };
 
 // --- Scope Defaults ---
@@ -80,6 +81,7 @@ function createConfigKey<T extends ConfigKeyType>(
     bounds: opts.bounds as ConfigBounds | undefined, // @cast-boundary schema-walk
     computed: opts.computed,
     ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
+    ...(opts.required === true ? { required: true } : {}),
   };
 }
 

package/src/engine/define-feature.ts

@@ -19,6 +19,7 @@ import type {
   EventDef,
   EventMigrationDef,
   EventUpcastFn,
+  ExtensionSelectorDef,
   FeatureDefinition,
   FeatureMetricDef,
   FeatureRegistrar,
@@ -129,6 +130,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const notifications: Record<string, NotificationDefinition> = {};
   const registrarExtensions: Record<string, RegistrarExtensionDef> = {};
   const extensionUsages: RegistrarExtensionRegistration[] = [];
+  const extensionSelectors: ExtensionSelectorDef[] = [];
   const exposedApis: Set<string> = new Set();
   const usedApis: Set<string> = new Set();
   const referenceData: ReferenceDataDef[] = [];
@@ -153,6 +155,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 
   let isSystemScoped = false;
   let toggleableDefault: boolean | undefined;
+  let description: string | undefined;
   // Visual-Tree-Slots — at-most-one per feature, only-once-guard im
   // registrar (siehe r.treeActions / r.tree). Undefined wenn das Feature
   // keinen Visual-Tree-Beitrag liefert (Zero-Whitelist-Filter).
@@ -182,6 +185,18 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       isSystemScoped = true;
     },
 
+    describe(text: string): void {
+      if (description !== undefined) {
+        throw new Error(
+          `[Feature ${name}] r.describe() called twice — a feature's description is declared once`,
+        );
+      }
+      if (typeof text !== "string" || text.trim().length === 0) {
+        throw new Error(`[Feature ${name}] r.describe(): text must be a non-empty string`);
+      }
+      description = text.trim();
+    },
+
     requires: (() => {
       const fn = (...featureNames: string[]) => {
         requires.push(...featureNames);
@@ -552,6 +567,17 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       extensionUsages.push({ extensionName, entityName: resolveName(entityRef), options });
     },
 
+    extensionSelector(extensionName: string, key: { readonly name: string } | string): void {
+      if (extensionSelectors.some((s) => s.extensionName === extensionName)) {
+        throw new Error(
+          `[Feature ${name}] extensionSelector("${extensionName}") declared twice — ` +
+            `one selector key per extension point.`,
+        );
+      }
+      const qualifiedKey = typeof key === "string" ? key : key.name;
+      extensionSelectors.push({ extensionName, qualifiedKey });
+    },
+
     /**
      * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
      * unter dem genannten Namen bereit. Die eigentliche Implementation
@@ -888,6 +914,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 
   return {
     name,
+    ...(description !== undefined && { description }),
     systemScope: isSystemScoped,
     exports,
     requires,
@@ -922,6 +949,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     notifications,
     registrarExtensions,
     extensionUsages,
+    extensionSelectors,
     exposedApis,
     usedApis,
     referenceData,

package/src/engine/feature-ast/extractors/index.ts

@@ -1,4 +1,5 @@
 export {
+  extractDescribe,
   extractOptionalRequires,
   extractReadsConfig,
   extractRequires,

package/src/engine/feature-ast/extractors/round1.ts

@@ -1,5 +1,6 @@
 import type { CallExpression, SourceFile } from "ts-morph";
 import type {
+  DescribePattern,
   OptionalRequiresPattern,
   ReadsConfigPattern,
   RequiresPattern,
@@ -12,6 +13,7 @@ import {
   fail,
   ok,
   readBooleanProperty,
+  readStringLiteralArgs,
   readVarargsOrArrayProp,
 } from "./shared";
 
@@ -82,6 +84,26 @@ export function extractSystemScope(
   });
 }
 
+export function extractDescribe(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<DescribePattern> {
+  const args = readStringLiteralArgs(call);
+  const text = args?.[0];
+  if (text === undefined || args?.length !== 1) {
+    return fail(
+      "describe",
+      sourceLocationFromNode(call, sourceFile),
+      "expected a single string literal",
+    );
+  }
+  return ok({
+    kind: "describe",
+    source: sourceLocationFromNode(call, sourceFile),
+    text,
+  });
+}
+
 export function extractToggleable(
   call: CallExpression,
   sourceFile: SourceFile,

package/src/engine/feature-ast/parse.ts

@@ -30,6 +30,7 @@ import {
   extractClaimKey,
   extractConfig,
   extractDefineEvent,
+  extractDescribe,
   extractEntity,
   extractEntityHook,
   extractEnvSchema,
@@ -297,6 +298,8 @@ function dispatchExtractor(
       return extractSystemScope(call, sourceFile);
     case "toggleable":
       return extractToggleable(call, sourceFile);
+    case "describe":
+      return extractDescribe(call, sourceFile);
     // Round 2 — object-literal-based static patterns
     case "entity":
       return extractEntity(call, sourceFile);

package/src/engine/feature-ast/patch.ts

@@ -79,6 +79,7 @@ export type PatternId =
   | { readonly kind: "readsConfig" }
   | { readonly kind: "systemScope" }
   | { readonly kind: "toggleable" }
+  | { readonly kind: "describe" }
   | { readonly kind: "config" }
   | { readonly kind: "translations" }
   | { readonly kind: "authClaims" }
@@ -270,6 +271,7 @@ export const SINGLETON_KINDS: ReadonlySet<PatternId["kind"]> = new Set([
   "readsConfig",
   "systemScope",
   "toggleable",
+  "describe",
   "config",
   "translations",
   "authClaims",
@@ -326,6 +328,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "readsConfig":
     case "systemScope":
     case "toggleable":
+    case "describe":
     case "config":
     case "translations":
     case "authClaims":

package/src/engine/feature-ast/patcher.ts

@@ -197,6 +197,7 @@ export type AddRequiresArgs = { readonly features: readonly string[] };
 export type AddOptionalRequiresArgs = { readonly features: readonly string[] };
 export type AddReadsConfigArgs = { readonly keys: readonly string[] };
 export type AddToggleableArgs = { readonly default: boolean };
+export type AddDescribeArgs = { readonly text: string };
 export type AddNavArgs = { readonly definition: NavDefinition };
 export type AddWorkspaceArgs = { readonly definition: WorkspaceDefinition };
 export type AddConfigArgs = {
@@ -223,6 +224,7 @@ export type FeaturePatcher = {
   readonly addReadsConfig: (args: AddReadsConfigArgs) => void;
   readonly addSystemScope: () => void;
   readonly addToggleable: (args: AddToggleableArgs) => void;
+  readonly addDescribe: (args: AddDescribeArgs) => void;
   readonly addEntity: (args: AddEntityArgs) => void;
   readonly addRelation: (args: AddRelationArgs) => void;
   readonly addNav: (args: AddNavArgs) => void;
@@ -300,6 +302,9 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
     addToggleable({ default: defaultOn }) {
       add({ kind: "toggleable", source: SYNTHETIC_LOC, default: defaultOn });
     },
+    addDescribe({ text }) {
+      add({ kind: "describe", source: SYNTHETIC_LOC, text });
+    },
     addEntity({ name, definition }) {
       add({
         kind: "entity",