gemi 0.56.0 → 0.58.0

package/dist/services/events/Listener.d.ts

@@ -0,0 +1,189 @@
+import type { Event, EventClass } from "./Event";
+/**
+ * One side effect of one event, in its own file.
+ *
+ * ```typescript
+ * // app/listeners/SendWelcomeEmail.ts
+ * export class SendWelcomeEmail extends Listener {
+ *   static name = "SendWelcomeEmail";
+ *   static event = UserRegistered;
+ *
+ *   async handle(event: UserRegistered) {
+ *     await Mail.send(event.email, ...);
+ *   }
+ * }
+ * ```
+ *
+ * That is the whole of what the subsystem buys: adding a fourth side effect to
+ * a registration is adding a file, rather than editing the controller that
+ * already has three.
+ *
+ * ### Why the binding lives here and not on the event
+ *
+ * The listener is the thing with an opinion about what it cares about; an event
+ * has no business knowing who is watching. An event listing its listeners would
+ * also put the property back the way it was — adding a side effect would edit
+ * an existing file.
+ *
+ * ### Why the binding is a value at all
+ *
+ * Laravel binds a listener to an event by reflecting on the type-hint of
+ * `handle(UserRegistered $event)`. TypeScript erases types at runtime, so that
+ * mechanism cannot exist here and the binding has to be carried as a value.
+ * That constraint turns out to be a favourable one: it is also what makes the
+ * payload types flow without a generated registry.
+ *
+ * ### The seam, written down rather than hidden
+ *
+ * **Nothing checks that `static event` and the annotation on `handle` agree.**
+ * A static and an instance member cannot reference each other's types, so the
+ * compiler sees `static event = UserRegistered` and `handle(event: OrderPaid)`
+ * as two unrelated declarations. Copy a listener, change the static, forget the
+ * annotation, and TypeScript is satisfied while the listener receives something
+ * else.
+ *
+ * It is accepted because the failure is local and immediate — that one listener
+ * reads a field that is not there, in its own stack — rather than the
+ * misroute-shaped failures the rest of this subsystem is arranged against. The
+ * `Listener.test-d.ts` beside this file pins the two halves the compiler *does*
+ * enforce, so a later refactor reaching for convenience cannot widen them to
+ * `any` unnoticed.
+ */
+export declare abstract class Listener {
+    /**
+     * The name this listener is reported and de-duplicated under. Required.
+     *
+     * Two listener classes claiming one name is refused at registration, and a
+     * discovery walk makes that ordinary: `auth/NotifyAdmins.ts` beside
+     * `billing/NotifyAdmins.ts` is a natural thing to write, and nothing forces
+     * the import alias a hand-written list would have demanded.
+     *
+     * As on `Event`, the `"unset"` default is a floor and not the check — a class
+     * declaration always shadows it with its own implicit binding, which is the
+     * one a minifier renames. `discoverListeners` reads the property descriptor
+     * to tell a declared name from an implicit one.
+     *
+     * For a **queued** listener it is more than a label: the queue is keyed by
+     * name, the listener is registered under `listener:<name>`, and that string
+     * is what a queued dispatch carries. So a queued listener whose name is the
+     * implicit class binding is refused at registration rather than warned about
+     * — the two ends of the queue can be two different module graphs, and a name
+     * only one of them minified is a side effect that stops happening in
+     * production and reports success.
+     */
+    static name: string;
+    /**
+     * The event class this listener handles. Exactly one, required.
+     *
+     * It holds the **class**, not its name. The name is read off it once, at
+     * registration, inside `EventManager.useListeners` — and that read happens in
+     * the module graph that declared the class, so the name it yields is the
+     * source one. Nothing downstream keeps the class object, because a registry
+     * keyed by class identity is wrong in production only.
+     *
+     * There is no `static events = [A, B]`, deliberately. A listener bound to two
+     * events has to discriminate inside `handle`, and the natural way to write
+     * that is `if (event instanceof UserRegistered)` — which is `true` in every
+     * test and `false` in a production build, for the reason `Event`'s own doc
+     * comment gives. Two events wanting the same side effect are two small
+     * listeners calling one shared function.
+     *
+     * Declared as required, and still checked at runtime: every subclass inherits
+     * this declaration whether or not it assigns to it, so the compiler cannot
+     * see a listener that left it out. `EventManager` refuses one out loud.
+     */
+    static event: EventClass;
+    /**
+     * Where this listener runs. **A context boundary, not a performance dial.**
+     *
+     * Left `false`, the listener runs inline, inside the dispatcher's
+     * `kernelContext` and `ormContext`: it has the request's `app()`, the
+     * authenticated user through `currentActor()`, and it joins the ambient
+     * transaction.
+     *
+     * **Unless the event declares `static afterCommit`.** That flag releases its
+     * listeners after the commit and outside the transaction's scope, so a sync
+     * listener bound to one runs with `currentTransaction()` undefined and
+     * commits on its own. The listener kept sync *because* it writes a row that
+     * has to roll back with the write it describes — an audit trail, a ledger
+     * entry — starts committing separately the day someone sets that flag in the
+     * event's file, and nothing on this side says so: no error, no warning, and
+     * a `queued = false` that still reads as "inside the transaction".
+     *
+     * Set `true`, it is handed to the `QueueManager` instead and run from a
+     * drain, on the queue's terms. What crosses is the event's name and its
+     * constructor arguments as JSON, and nothing else — not the instance the sync
+     * listeners share, and not a line of the request. With `worker = true` it is
+     * a different thread with a cloned application.
+     *
+     * The part that catches people is that the context is not reliably *gone*
+     * either: the queue is in-process, so a drain that happens to start from
+     * `push` is still standing in the dispatcher's context and `app()` there
+     * resolves the request's application. Nothing about that is promised. A
+     * queued listener that reads the current actor, or writes expecting to join
+     * the ambient transaction, works until the day the queue was already busy —
+     * and then reads different rows, or commits separately, with no error either
+     * way. So: a listener that needs the request's context has to stay sync, and
+     * a listener that only needs the payload is free to queue.
+     *
+     * What it buys, in exchange, is the queue's whole retry path: `maxAttempts`,
+     * `onFail`-style re-queueing and dead-lettering, none of which a sync
+     * listener has. `dispatchAndWait` does **not** wait for it.
+     */
+    queued: boolean;
+    /**
+     * Attempts before the queue gives up, counting the first. `Job`'s field and
+     * `Job`'s meaning, because it is forwarded to one.
+     *
+     * **Ignored unless `queued` is true.** A sync listener has no retry path at
+     * all — its throw is logged and the next listener runs — so a `maxAttempts`
+     * beside `queued = false` is a line that does nothing, which is why it is
+     * said here rather than in a note somewhere else.
+     */
+    maxAttempts: number;
+    /**
+     * Runs `handle` in a Worker thread with its own cloned application, for a
+     * queued listener whose work is CPU-bound. `Job`'s field and `Job`'s
+     * meaning, because it is forwarded to one.
+     *
+     * **Ignored unless `queued` is true.** A sync listener runs on the
+     * dispatcher's stack by definition; there is no thread to move it to.
+     */
+    worker: boolean;
+    /**
+     * The side effect. Runs inside the dispatcher's context when `queued` is
+     * false: a sync listener has the request's `app()`, its authenticated user,
+     * and — unless the event declares `static afterCommit` — its ambient
+     * transaction. A queued one can rely on none of them — see `queued`.
+     *
+     * Annotate the parameter with the event named in `static event` — narrowing
+     * the base's `Event` here is legal because method parameters are bivariant,
+     * which is what lets this class avoid a generic parameter. Nothing checks
+     * that the two agree; see the note on the class.
+     *
+     * Abstract, so a listener that forgets it fails to compile rather than
+     * silently handling nothing.
+     *
+     * A throw is caught, logged with both names, and the next listener still
+     * runs. Listeners are independent side effects by construction, and their
+     * order is a filesystem walk's — letting one cancel the rest would make that
+     * order load-bearing, which is the exact coupling this subsystem exists to
+     * remove.
+     */
+    abstract handle(event: Event): void | Promise<void>;
+}
+/**
+ * A `Listener` subclass, as the registry and the `events` config slice hold
+ * one.
+ *
+ * Zero-argument, because the manager constructs one per dispatch and has
+ * nothing to pass it. The `event` member is typed as present even though
+ * `EventManager` checks for it at runtime: an inherited declaration is
+ * indistinguishable from an assignment to the type system, so this is the
+ * shape, and the runtime check is what covers the difference.
+ */
+export type ListenerClass = (new () => Listener) & {
+    name: string;
+    event: EventClass;
+};
+//# sourceMappingURL=Listener.d.ts.map

package/dist/services/events/Listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Listener.d.ts","sourceRoot":"","sources":["../../../services/events/Listener.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,8BAAsB,QAAQ;IAC5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,IAAI,SAAW;IAEtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,MAAM,UAAS;IAEf;;;;;;;;OAQG;IACH,WAAW,SAAK;IAEhB;;;;;;;OAOG;IACH,MAAM,UAAS;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,UAAU,QAAQ,CAAC,GAAG;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC"}

package/dist/services/events/Listener.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Listener.test-d.d.ts.map

package/dist/services/events/Listener.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Listener.test-d.d.ts","sourceRoot":"","sources":["../../../services/events/Listener.test-d.ts"],"names":[],"mappings":""}

package/dist/services/events/config.d.ts

@@ -0,0 +1,55 @@
+import type { ListenerClass } from "./Listener";
+export interface EventConfig {
+    /**
+     * The `Listener` subclasses this application registers, or nothing.
+     *
+     * ### Why "or nothing" is the point
+     *
+     * A dispatch fans out to whatever the `EventManager` holds for the event's
+     * name, and an event nothing is registered for is not an error — it is the
+     * ordinary state of an application that has not written that listener yet.
+     * So this list is a second spelling of `app/listeners`, kept in step by hand,
+     * and what the two disagreeing costs is a side effect that stops happening,
+     * with a development-only warning as the only trace. Nothing fails, nothing
+     * is dropped from a log: the welcome email simply is not sent.
+     *
+     * Leaving this out spells it once: the listeners are the classes under
+     * `listenersDir`.
+     *
+     * ### The rule, exactly
+     *
+     * **Declared wins, and `[]` is declared.** A `listeners` that is present is
+     * used verbatim and no directory is read — that is the escape hatch for an
+     * app whose listeners live somewhere this cannot walk, for one that
+     * deliberately registers a subset, and for a deploy that ships no source. An
+     * empty array means an app with no listeners and says so; it does not mean
+     * "find some".
+     *
+     * **Absent or `undefined` discovers.** `undefined` counts as absent for the
+     * same reason `withDefaults` treats it that way everywhere else: a key spread
+     * in from an optional value is an omission, not an instruction.
+     */
+    listeners?: ListenerClass[];
+    /**
+     * Where to look when `listeners` was not declared. Relative to the project
+     * root, or absolute.
+     *
+     * Every `.ts`/`.tsx` file underneath it is imported at boot and every
+     * exported class extending `Listener` is registered, so this wants to be a
+     * directory of listener declarations rather than a directory that merely
+     * contains some. That includes an abstract base a few listeners share: the
+     * walk excludes the framework's `Listener` and nothing else, so a base
+     * sitting here is registered alongside its subclasses and its `handle` runs
+     * on every dispatch of whatever event it declares. Keep shared bases outside
+     * this directory.
+     *
+     * There is no `eventsDir` to go with it. Event classes are never discovered
+     * — each is imported by the listener that binds to it and by the code that
+     * dispatches it, so nothing needs to walk them and a walk that imported them
+     * anyway would only be a boot cost.
+     */
+    listenersDir?: string;
+}
+export declare function defineEventConfig(config: EventConfig): EventConfig;
+export declare function eventConfigDefaults(): Required<EventConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/services/events/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../services/events/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAE5B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAElE;AAED,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,WAAW,CAAC,CAK3D"}

package/dist/services/events/listenerJob.d.ts

@@ -0,0 +1,43 @@
+import { Job } from "../queue/Job";
+import type { Listener, ListenerClass } from "./Listener";
+/**
+ * The adapter that lets `queued = true` be one line: a `Job` subclass, built at
+ * registration, that runs exactly one listener.
+ *
+ * Retries, `maxAttempts`, dead-lettering, `concurrency` and worker-thread
+ * execution are four features the queue already has, already documents for
+ * applications, and is already tested on. A second queue for listeners would be
+ * four features that are almost the same as those, differing in ways nobody
+ * decided. So a queued listener is not queued by anything written here — it is
+ * a job, and everything after `push` is the queue's.
+ */
+/**
+ * The name a listener's synthetic job is registered under.
+ *
+ * Prefixed, and visibly so. The synthetic jobs land in
+ * `QueueManager.registeredJobs` alongside the app's own, because that getter is
+ * documented as reporting what the manager was handed and a queued listener
+ * genuinely is something the queue will run — hiding them would make a queue
+ * introspection tool lie about what is about to execute. The prefix is what
+ * keeps an author from reading `SendWelcomeEmail` there and looking for a job
+ * file they never wrote.
+ */
+export declare function listenerJobName(listenerName: string): string;
+/**
+ * Builds the `Job` subclass that runs one queued listener.
+ *
+ * `instance` is the listener the caller already constructed to read `queued`
+ * off; the three fields that decide where the work runs are read from that one
+ * instance rather than from a fresh one per attempt, so a listener's
+ * constructor runs once at boot instead of once per retry.
+ *
+ * What crosses the queue is `[eventName, constructorArguments]` as JSON — a
+ * name and the arguments, never the event instance and never the classes. That
+ * is invariant 1 at its second boundary: the class objects on the pushing side
+ * and the running side can come from two different module graphs (a minified
+ * bundle and a source-side discovery walk), so a name declared as a string
+ * literal is the only thing both ends agree on. `EventManager.rehydrate` turns
+ * it back into an event.
+ */
+export declare function jobForListener(listener: ListenerClass, instance: Listener): new () => Job;
+//# sourceMappingURL=listenerJob.d.ts.map

package/dist/services/events/listenerJob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listenerJob.d.ts","sourceRoot":"","sources":["../../../services/events/listenerJob.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,QAAQ,GACjB,UAAU,GAAG,CAiFf"}

package/dist/services/features/FeatureFlagStore.d.ts

@@ -0,0 +1,60 @@
+import type { FeatureRegistry } from "./defineFeature";
+import type { FeatureFlagSource } from "./sources/FeatureFlagSource";
+export type Warn = (message: string) => void;
+export interface FlagSnapshot {
+    /** `key -> active`. A key absent from the map has no row, and is off. */
+    active: Map<string, boolean>;
+    loadedAt: number;
+    /** True only while nothing has *ever* loaded successfully. */
+    unavailable: boolean;
+}
+/**
+ * The process-local cache of on/off switches.
+ *
+ * gemi has no `Cache` facade, and this does not add one — a general cache
+ * abstraction is a much larger design, and coupling features to a hypothetical
+ * version of it would block both.
+ *
+ * Three properties, each load-bearing:
+ *
+ * **Stale-while-revalidate.** After the first load, `get()` returns an
+ * already-resolved snapshot and refreshes in the background. No request ever
+ * waits on the database for a feature. This is what makes evaluating every
+ * feature on every request affordable, and it is why the manager can be eager.
+ *
+ * **Single-flight.** A cold start under load must not issue one query per
+ * in-flight request, so concurrent refreshes share one promise.
+ *
+ * **A failed refresh keeps the last good data.** An outage must not read as
+ * "every feature switched itself off" — that is a config change nobody made,
+ * applied to production, at the exact moment something else is already broken.
+ */
+export declare class FeatureFlagStore {
+    private readonly source;
+    private readonly declared;
+    private readonly ttlMs;
+    private readonly warn;
+    private snapshot;
+    private inflight;
+    /** Rate-limits the "could not load" line to once per TTL window. */
+    private lastFailureLoggedAt;
+    constructor(source: FeatureFlagSource, declared: FeatureRegistry, ttlMs: number, warn?: Warn);
+    /** Never rejects. Callers always get a snapshot, possibly an empty one. */
+    get(): Promise<FlagSnapshot>;
+    /** Forces a reload now, sharing one query across concurrent callers. */
+    refresh(): Promise<FlagSnapshot>;
+    /** What is cached right now, without triggering a load. */
+    peek(): FlagSnapshot | null;
+    private load;
+    /**
+     * Rows in, `key -> active` out.
+     *
+     * The row is treated as hostile input — not because anyone expects it to be
+     * malformed, but because it is the one part of this system nobody reviews
+     * before it reaches production. A bad row is logged and skipped, never thrown:
+     * a typo in a column must not take the process down at boot.
+     */
+    private readSwitches;
+    private handleFailure;
+}
+//# sourceMappingURL=FeatureFlagStore.d.ts.map

package/dist/services/features/FeatureFlagStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureFlagStore.d.ts","sourceRoot":"","sources":["../../../services/features/FeatureFlagStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB;IAOzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAAsC;IACtD,oEAAoE;IACpE,OAAO,CAAC,mBAAmB,CAAK;gBAGb,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,IAAe;IAGxC,2EAA2E;IACrE,GAAG,IAAI,OAAO,CAAC,YAAY,CAAC;IAiBlC,wEAAwE;IACxE,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC;IAOhC,2DAA2D;IAC3D,IAAI,IAAI,YAAY,GAAG,IAAI;YAIb,IAAI;IAclB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,aAAa;CAkBtB"}

package/dist/services/features/FeatureManager.d.ts

@@ -0,0 +1,82 @@
+import type { ResolvedFeaturesConfig } from "./config";
+import { type FeatureSubject } from "./context";
+import type { FeatureRegistry } from "./defineFeature";
+import { FeatureFlagStore } from "./FeatureFlagStore";
+import type { FeatureContext, FeatureEvaluation } from "./types";
+/**
+ * Evaluation bound to one explicit context — what `Features.for(...)` returns.
+ *
+ * Exists because a job, a cron tick or an admin preview needs to ask "what would
+ * *this* user see", and the ambient-request path cannot answer that.
+ */
+export declare class FeatureScope {
+    private readonly manager;
+    private readonly ctx;
+    constructor(manager: FeatureManager, ctx: FeatureContext);
+    enabled(key: string): Promise<boolean>;
+    explain(key: string): Promise<FeatureEvaluation>;
+    all(): Promise<Record<string, boolean>>;
+}
+export declare class FeatureManager {
+    readonly config: ResolvedFeaturesConfig;
+    private readonly log;
+    static token: string;
+    readonly store: FeatureFlagStore;
+    private readonly declared;
+    private warnedAboutSize;
+    constructor(config: ResolvedFeaturesConfig, log?: (message: string) => void);
+    /** The declarations, for a CLI or an admin surface. Server-side only. */
+    declarations(): FeatureRegistry;
+    /** Reloads the snapshot in this process now. */
+    refresh(): Promise<void>;
+    enabled(key: string): Promise<boolean>;
+    /**
+     * Value plus why. Server-side only — `reason` says whether the viewer landed
+     * in a rollout or was targeted by name, and must never be serialized.
+     */
+    explain(key: string): Promise<FeatureEvaluation>;
+    /** Every declared feature for the ambient request, as `key -> boolean`. */
+    all(): Promise<Record<string, boolean>>;
+    /**
+     * What the SSR payload carries: client-visible features only.
+     *
+     * The single function the dispatcher calls, and the only place the server-only
+     * exclusion is applied — so "what reaches the browser" has one answer in one
+     * place rather than a rule each caller has to remember.
+     */
+    forClient(): Promise<Record<string, boolean>>;
+    /** Evaluation against an explicit subject, for jobs, cron and previews. */
+    for(subject: FeatureSubject): FeatureScope;
+    /**
+     * @internal — shared by the ambient path and `FeatureScope`. The single place
+     * a feature is evaluated, and therefore the single place the per-request memo
+     * is consulted and `onEvaluate` fires.
+     *
+     * Both of those used to live in `explain()`, one level up, which meant every
+     * caller that did not go through it — `forClient()` building the SSR payload,
+     * `passesFeatureGates` checking a route — evaluated afresh and notified again.
+     * A request that read a feature in a handler and then rendered it emitted two
+     * exposures for one viewer, quietly doubling whatever counted them.
+     */
+    evaluateIn(key: string, ctx: FeatureContext, buckets: Map<string, number>): Promise<FeatureEvaluation>;
+    /** @internal */
+    evaluateAllIn(ctx: FeatureContext, buckets: Map<string, number>, options: {
+        clientOnly: boolean;
+    }): Promise<Record<string, boolean>>;
+    private switchFor;
+    private requestContext;
+    /**
+     * The request's evaluation memo, or `null` when there is none to use.
+     *
+     * Gated on the context being the ambient request's *own*, by identity. A
+     * `Features.for({ user })` inside a request is asking what somebody else would
+     * see, and answering it from — or writing it into — the current viewer's memo
+     * would cross the two: an admin previewing a customer would poison every
+     * subsequent read on that request with the customer's values.
+     */
+    private memoFor;
+    private requestBuckets;
+    private notify;
+    private warnIfOversized;
+}
+//# sourceMappingURL=FeatureManager.d.ts.map

package/dist/services/features/FeatureManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureManager.d.ts","sourceRoot":"","sources":["../../../services/features/FeatureManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAA0C,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;;GAKG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,cAAc;IAGhC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIhD,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAK9C;AAED,qBAAa,cAAc;IAQvB,QAAQ,CAAC,MAAM,EAAE,sBAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG;IARtB,MAAM,CAAC,KAAK,SAAc;IAE1B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,eAAe,CAAS;gBAGrB,MAAM,EAAE,sBAAsB,EACtB,GAAG,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe;IAe5D,yEAAyE;IACzE,YAAY,IAAI,eAAe;IAI/B,gDAAgD;IAC1C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5C;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKtD,2EAA2E;IACrE,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAO7C;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAWnD,2EAA2E;IAC3E,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY;IAI1C;;;;;;;;;;OAUG;IACG,UAAU,CACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAyB7B,gBAAgB;IACV,aAAa,CACjB,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAWrB,SAAS;YAgBT,cAAc;IAS5B;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,eAAe;CAOxB"}

package/dist/services/features/FeaturesServiceProvider.d.ts

@@ -0,0 +1,6 @@
+import { ServiceProvider } from "../../support/ServiceProvider";
+export declare class FeaturesServiceProvider extends ServiceProvider {
+    register(): void;
+    boot(): Promise<void>;
+}
+//# sourceMappingURL=FeaturesServiceProvider.d.ts.map

package/dist/services/features/FeaturesServiceProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeaturesServiceProvider.d.ts","sourceRoot":"","sources":["../../../services/features/FeaturesServiceProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAMhE,qBAAa,uBAAwB,SAAQ,eAAe;IAC1D,QAAQ;IAqCF,IAAI;CAkBX"}

package/dist/services/features/bucket.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Deterministic bucketing for percentage rollouts.
+ *
+ * ## Why nothing is stored
+ *
+ * A subject's bucket is a pure function of the feature and the subject, so it is
+ * the same on every machine, in every process, on every device that subject logs
+ * in from, forever — without a row, a cookie, or a cache holding the assignment.
+ * Persisting assignments would be strictly worse: it would be per-browser rather
+ * than per-subject, it would need migrating whenever a feature changes, and it
+ * would grow with the user count.
+ *
+ * ## Why SHA-1 and not `Bun.hash`
+ *
+ * `Bun.hash` is faster and wrong for this. Its output is seeded and is not a
+ * documented stable contract across Bun versions, so a runtime upgrade could
+ * silently re-bucket every subject in the middle of a rollout — the 10% who had
+ * the new checkout become a different 10%, and nobody finds out from a stack
+ * trace. SHA-1 is a fixed standard: the same string maps to the same bucket on
+ * every machine, every process and every version. This is a correctness
+ * requirement, not a security one, so SHA-1's collision weakness is irrelevant
+ * here — and `Bun.CryptoHasher("sha1")` is already how `server/generateEtag.ts`
+ * hashes.
+ *
+ * ## What is in the key
+ *
+ * `salt:subject`, where `salt` defaults to the feature's key.
+ *
+ * The salt is what decorrelates features from each other. Without it two
+ * independent 20% rollouts would select the *same* 20% of subjects, so a user
+ * unlucky once would be unlucky in everything and the two populations could
+ * never be reasoned about separately.
+ */
+declare const RESOLUTION = 10000;
+/** The bucket key. Exported so a test can pin exact strings to exact buckets. */
+export declare function bucketKey(salt: string, subject: string): string;
+/**
+ * A stable integer in `[0, RESOLUTION)` — i.e. 0.01% granularity.
+ *
+ * Takes the first 32 bits of the digest. That is four orders of magnitude more
+ * entropy than the 10,000 buckets it is reduced to, so the modulo bias is far
+ * below the noise floor of any rollout anyone would configure.
+ */
+export declare function bucketOf(key: string): number;
+/**
+ * Whether `bucket` falls inside `percent`.
+ *
+ * `bucket < threshold` rather than a range test, which buys monotonicity for
+ * free: a subject inside a 10% rollout is still inside the same feature's 20%
+ * rollout. Ramping up therefore only ever *adds* people. The alternative —
+ * anything that reshuffles on each change — means a user who saw the feature at
+ * 10% can lose it at 20%, which reads as a bug to them and invalidates any
+ * measurement taken across the change.
+ */
+export declare function inRollout(bucket: number, percent: number): boolean;
+export { RESOLUTION };
+//# sourceMappingURL=bucket.d.ts.map

package/dist/services/features/bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.d.ts","sourceRoot":"","sources":["../../../services/features/bucket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,QAAA,MAAM,UAAU,QAAS,CAAC;AAE1B,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAIlE;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/services/features/config.d.ts

@@ -0,0 +1,57 @@
+import type { HttpRequest } from "../../http/HttpRequest";
+import type { FeatureRegistry } from "./defineFeature";
+import type { FeatureFlagSource } from "./sources/FeatureFlagSource";
+import type { FeatureContext, FeatureEvaluation } from "./types";
+export interface FeaturesConfig {
+    /**
+     * The application's declarations — the default export of
+     * `app/features/index.ts`.
+     *
+     * Named here as well as in the framework's `gemi.d.ts` because the two layers
+     * cannot share one reference: the type augmentation resolves `@/app/features`
+     * through the app's tsconfig paths, which exists only at compile time. This is
+     * the runtime half. They should point at the same object.
+     */
+    features?: FeatureRegistry;
+    /**
+     * Master switch. `false` skips loading and evaluation entirely: every feature
+     * reads off and the SSR payload carries `{}`.
+     */
+    enabled?: boolean;
+    /** Where the on/off switches come from. The database by default. */
+    source?: FeatureFlagSource;
+    /** ORM registry name of the model, when using the database source. */
+    model?: string;
+    /**
+     * Snapshot lifetime in **seconds**.
+     *
+     * This is the propagation delay: switching a feature on or off is live on
+     * every instance within this window. Lower it if that matters more than the
+     * query volume — there is no cross-instance invalidation.
+     */
+    ttl?: number;
+    /**
+     * Extra attributes for every evaluation — country, cohort, build, plan.
+     * Reachable in a `when` as `ctx.attributes`.
+     *
+     * Runs on every request inside the render path, so keep it cheap and free of
+     * I/O. If it throws, evaluation degrades to no attributes rather than failing
+     * the page.
+     */
+    context?: (req: HttpRequest | null) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Called once per key per request after evaluation — the hook an analytics or
+     * experiment pipeline reads exposures from. Errors are caught and logged.
+     */
+    onEvaluate?: (key: string, evaluation: FeatureEvaluation, ctx: FeatureContext) => void;
+    /** Warn once per boot above this many client-visible features. */
+    maxClientFlags?: number;
+}
+export declare function defineFeaturesConfig(config: FeaturesConfig): FeaturesConfig;
+export declare function featuresConfigDefaults(): Required<Omit<FeaturesConfig, "features" | "context" | "onEvaluate">> & {
+    features: FeaturesConfig["features"];
+    context: FeaturesConfig["context"];
+    onEvaluate: FeaturesConfig["onEvaluate"];
+};
+export type ResolvedFeaturesConfig = ReturnType<typeof featuresConfigDefaults>;
+//# sourceMappingURL=config.d.ts.map

package/dist/services/features/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../services/features/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAGjE,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAE3B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,oEAAoE;IACpE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAElG;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IAEvF,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAE3E;AAED,wBAAgB,sBAAsB,IAAI,QAAQ,CAChD,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC,CAC5D,GAAG;IACF,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACnC,UAAU,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;CAC1C,CAWA;AAED,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/services/features/context.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedFeaturesConfig } from "./config";
+import type { FeatureContext } from "./types";
+export interface FeatureSubject {
+    user?: Record<string, any> | null;
+    attributes?: Record<string, unknown>;
+    /** The bucketing subject when there is no user — an org id, a device id. */
+    subjectId?: string;
+}
+/**
+ * Builds the context a feature is evaluated against from the ambient request.
+ *
+ * Two decisions worth stating:
+ *
+ * **The user comes from the request store, not `Auth.user()`.** `Auth.user()`
+ * throws `AuthenticationError` when nobody is signed in and performs a session
+ * lookup to find out. Features have to be evaluable on an anonymous marketing
+ * page without either, so this reads `store.user` and accepts `null`. The
+ * consequence is worth knowing: on a route with no `auth` middleware, where
+ * nothing has resolved a session, `ctx.user` is `null` and a `when` that reads
+ * it will not match. The fix an application reaches for is the `auth` middleware
+ * it already has.
+ *
+ * **No request is not an error.** A job, a cron tick or a console command has no
+ * store, and `Features.enabled()` there answers with an anonymous context rather
+ * than throwing. `Features.for({ user })` is the explicit form when a background
+ * task needs to evaluate as somebody.
+ */
+export declare function contextFromRequest(config: ResolvedFeaturesConfig, warn?: (message: string) => void): Promise<FeatureContext>;
+/** The same shape, from an explicit subject rather than the ambient request. */
+export declare function contextFromSubject(subject: FeatureSubject): FeatureContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/services/features/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../services/features/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,sBAAsB,EAC9B,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,GACzC,OAAO,CAAC,cAAc,CAAC,CAyBzB;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAc1E"}