@adonis-agora/flags 0.0.0-beta-20261112141227

package/dist/src/declare.js

@@ -0,0 +1,62 @@
+/** Builders for flag declarations, used in `config/flags.ts`. */
+export const flag = {
+    /** An on/off flag. */
+    boolean(options) {
+        return { ...options, type: 'boolean' };
+    },
+    /**
+     * A string flag. With `variants`, the flag is a multivariate experiment and its type narrows to
+     * the listed names.
+     */
+    string(options) {
+        if (options.variants && !options.variants.includes(options.default)) {
+            throw new Error(`flag default "${options.default}" is not one of its variants`);
+        }
+        return { ...options, type: 'string' };
+    },
+    /** A numeric flag (limits, thresholds, percentages). */
+    number(options) {
+        return { ...options, type: 'number' };
+    },
+    /** A JSON payload flag (configuration objects). */
+    json(options) {
+        return { ...options, type: 'json' };
+    },
+};
+/** A JSON-safe copy of the declarations, as pushed to a control-plane and shown in the console. */
+export function serializeDeclarations(declarations) {
+    return JSON.parse(JSON.stringify(declarations));
+}
+/**
+ * Every flag this app knows about: declared in code, or created in the console (the declaration
+ * travels in the ruleset). Code wins when both exist.
+ */
+export function effectiveDeclarations(code, ruleset) {
+    const out = {};
+    for (const [key, definition] of Object.entries(ruleset.flags)) {
+        if (definition.declaration)
+            out[key] = { ...fromData(definition.declaration), source: 'console' };
+    }
+    for (const [key, declaration] of Object.entries(code))
+        out[key] = { ...declaration, source: 'code' };
+    return out;
+}
+/** A ruleset declaration as a {@link FlagDeclaration}. */
+export function fromData(data) {
+    return { ...data };
+}
+/** A {@link FlagDeclaration} as ruleset data (what the console stores). */
+export function toData(declaration) {
+    const { type, default: value, variants, description, owner, expiresAt, tags, client, } = declaration;
+    return {
+        type,
+        default: value,
+        ...(variants ? { variants: [...variants] } : {}),
+        ...(description ? { description } : {}),
+        ...(owner ? { owner } : {}),
+        ...(expiresAt ? { expiresAt } : {}),
+        ...(tags?.length ? { tags: [...tags] } : {}),
+        ...(client !== undefined ? { client } : {}),
+    };
+}
+//# sourceMappingURL=declare.js.map

package/dist/src/declare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declare.js","sourceRoot":"","sources":["../../src/declare.ts"],"names":[],"mappings":"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"}

package/dist/src/define_config.d.ts

@@ -0,0 +1,256 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ApplicationService } from '@adonisjs/core/types';
+import type { AdminAuthorizer, ApprovalsConfig } from './admin.js';
+import type { AnalyticsBackend } from './analytics/backend.js';
+import { type DuckDbOptions } from './analytics/duckdb.js';
+import type { MetricDefinition } from './analytics/metrics.js';
+import type { FlagDeclaration } from './declare.js';
+import type { Enricher } from './enrichers.js';
+import type { BufferOptions } from './events/buffer.js';
+import type { FlagEvent } from './events/event.js';
+import type { FlagsIdentityProvider } from './identity.js';
+import type { RelayOptions } from './relay/relay.js';
+import { type ClickHouseOptions } from './sinks/clickhouse.js';
+import { type ParquetSinkOptions } from './sinks/parquet_sink.js';
+import { type PostHogSinkOptions } from './sinks/posthog_sink.js';
+import { type Sink } from './sinks/sink.js';
+import type { SqlDatabase } from './sql.js';
+import { MemoryStore } from './stores/memory_store.js';
+import type { FlagsStore } from './stores/store.js';
+import type { Subject, SubjectLike } from './subject.js';
+import type { TokenSource } from './topology/token.js';
+import type { TenantVerifier, UserVerifier } from './topology/verify.js';
+import { type DbTransportOptions } from './transports/db_transport.js';
+import { type RedisStreamClient, type RedisTransportOptions } from './transports/redis_transport.js';
+import type { Transport } from './transports/transport.js';
+/** What factories receive: the app and lazy access to its database and Redis connections. */
+export interface FactoryContext {
+    app?: ApplicationService;
+    /** The application's name (its package.json `name`), the default `app` stamped on events. */
+    appName?: string | undefined;
+    /** A Lucid query client for `connection` (default connection when omitted). */
+    db(connection?: string): Promise<SqlDatabase>;
+    redis(connection?: string): Promise<RedisStreamClient>;
+    autoCreateSchema: boolean;
+    partitionEvents: boolean;
+}
+export type Factory<T> = (context: FactoryContext) => T | Promise<T>;
+export declare const stores: {
+    /** The ruleset in your database (Postgres, MySQL, SQLite). The default. */
+    lucid(options?: {
+        connection?: string;
+    }): Factory<FlagsStore>;
+    /** In process memory: tests and local development. */
+    memory(seed?: ConstructorParameters<typeof MemoryStore>[0]): Factory<FlagsStore>;
+};
+export declare const transports: {
+    /** The event log in your database. Transactional; the default when the store is `lucid`. */
+    db(options?: DbTransportOptions & {
+        connection?: string;
+    }): Factory<Transport>;
+    /** Redis Streams through `@adonisjs/redis`. */
+    redis(options?: RedisTransportOptions & {
+        connection?: string;
+    }): Factory<Transport>;
+    /** In process memory: tests and local development. */
+    memory(): Factory<Transport>;
+};
+export declare const sinks: {
+    /** Analysis tables in your database (`flags_exposures`, `flags_tracks`); read by `analytics.lucid()`. */
+    lucid(options?: {
+        connection?: string;
+        batchSize?: number;
+        intervalMs?: number;
+    }): Factory<Sink>;
+    posthog(options: PostHogSinkOptions): Factory<Sink>;
+    clickhouse(options: ClickHouseOptions & {
+        batchSize?: number;
+        intervalMs?: number;
+        autoCreateSchema?: boolean;
+    }): Factory<Sink>;
+    /** Parquet files through DuckDB (`@duckdb/node-api`); read by `analytics.duckdb()`. */
+    parquet(options: ParquetSinkOptions): Factory<Sink>;
+    /** Your function receives every batch. Must be idempotent by `event.id`. */
+    callback(fn: (events: FlagEvent[]) => Promise<void>, options?: {
+        batchSize?: number;
+        intervalMs?: number;
+    }): Factory<Sink>;
+    memory(): Factory<Sink>;
+};
+export declare const analytics: {
+    lucid(options?: {
+        connection?: string;
+    }): Factory<AnalyticsBackend>;
+    duckdb(options: DuckDbOptions & {
+        path: string;
+    }): Factory<AnalyticsBackend>;
+    clickhouse(options: ClickHouseOptions): Factory<AnalyticsBackend>;
+};
+/** An experiment's analysis: which metrics decide it and which must not regress. */
+export interface ExperimentConfig {
+    metrics: string[];
+    guardrails?: string[];
+    /** Control variant. Default: the flag's `offVariant`. */
+    control?: string;
+    /** Confidence for fixed-horizon tests. Default 0.95. */
+    confidence?: number;
+    /** The flag that assigns it, when the experiment key differs from the flag key. */
+    flag?: string;
+}
+interface BaseConfig<F extends Record<string, FlagDeclaration>> {
+    /** Flags declared in code: types and defaults. Targeting lives in the store. */
+    flags: F;
+    /** Name stamped on events (a tenant uses its `partition`). Default: the app's name. */
+    app?: string;
+    /** Which environment's ruleset this process reads. Default `production`. */
+    environment?: string;
+    /** Which part of a split deployment this process is. Default `all`. See the ecosystem spec. */
+    role?: 'all' | 'api' | 'worker';
+    /** How background work (relay, schedules, results) runs. Default `auto`. */
+    dispatcher?: 'auto' | 'durable' | 'in-process';
+    events?: {
+        buffer?: BufferOptions;
+    };
+    enrichers?: Enricher[];
+    /**
+     * How flags learns who people are: the subject of `ctx.flags`, the console's actor and access, and
+     * who may change what. `identities.authkit()`, `identities.adonisAuth({ … })`, or your own
+     * `FlagsIdentityProvider`. Default: the authkit identity when `@adonis-agora/authkit-client` is
+     * installed, else `ctx.auth.user`; the console keeps its own defaults.
+     */
+    identity?: FlagsIdentityProvider;
+    /**
+     * The subject of `ctx.flags`, overriding `identity`. Default: the identity provider's, else the
+     * authkit identity, else `ctx.auth.user`, else anonymous.
+     */
+    subject?: (ctx: HttpContext) => SubjectLike | Promise<SubjectLike>;
+    /** Extra targeting attributes for every subject. Server-side state only. */
+    attributes?: (subject: Subject) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Count evaluations per flag for stale-flag detection. Default `true`. */
+    usage?: boolean;
+    /**
+     * Frontends that read flags straight from the flags API (`remoteFlags` in
+     * `@adonis-agora/flags-react`). Turns on, in every topology, the token endpoint
+     * (`GET /_flags/token`): it signs the same subject `ctx.flags` uses — the authkit identity, or your
+     * `subject` resolver — into a short-lived token. On standalone and control-plane apps it also
+     * serves the flags API the token is for (`<prefix>/v1/client/*`).
+     */
+    browser?: BrowserConfig;
+}
+export interface BrowserConfig {
+    /** Path of the token endpoint on this app. Default `/_flags/token`; `false` to mount none. */
+    tokenRoute?: string | false;
+    /** Token lifetime in seconds. Default 300. */
+    ttlSeconds?: number;
+    /**
+     * The flags API URL handed to the browser with each token. Default: this app's `/_flags`
+     * (standalone, control-plane) or `tenant.url` (tenant). Set it when browsers reach the flags
+     * server under another address than the app does.
+     */
+    publicUrl?: string;
+    /** Standalone and control-plane: route prefix of the flags API. Default `/_flags` (or `controlPlane.prefix`). */
+    prefix?: string;
+    /** Standalone and control-plane: origins allowed to call the flags API cross-origin. */
+    corsOrigins?: string[];
+    /**
+     * Standalone and control-plane: secret the per-app signing keys derive from. Default: the app key
+     * (`APP_KEY`). Rotating it invalidates outstanding tokens; frontends fetch new ones.
+     */
+    secret?: string;
+    /**
+     * Standalone and control-plane: also accept tokens this package did not mint — e.g.
+     * `userVerifiers.authkit(...)` for authkit access tokens held by mobile apps.
+     */
+    verifyUser?: UserVerifier;
+}
+interface OwnedStateConfig {
+    /** Where the ruleset lives. Default `stores.lucid()`. */
+    store?: Factory<FlagsStore>;
+    /** Default: `db` with a lucid store, `memory` with a memory store. */
+    transport?: Factory<Transport>;
+    /** Event destinations, by name. Default `{ warehouse: sinks.lucid() }` with a lucid store. */
+    sinks?: Record<string, Factory<Sink>>;
+    relay?: RelayOptions & {
+        /** How often each sink is drained (ms). Default 5000. */
+        intervalMs?: number;
+    };
+    /** Ruleset reload: poll interval and Postgres notifications. */
+    refresh?: {
+        intervalMs?: number;
+        notify?: boolean;
+    };
+    /** Where experiment numbers come from. Default `analytics.lucid()` when the lucid sink exists. */
+    analytics?: Factory<AnalyticsBackend>;
+    metrics?: Record<string, MetricDefinition>;
+    /** Experiment key → its metrics. */
+    experiments?: Record<string, ExperimentConfig>;
+    /**
+     * Environments whose experiment results the worker recomputes. Default: this process's
+     * `environment`. Events carry their environment, so staging traffic never mixes with production.
+     */
+    resultsEnvironments?: string[];
+    /** How often the worker recomputes experiment results (ms). Default 600000. */
+    resultsIntervalMs?: number;
+    /**
+     * Keep subjects on the variant they were first exposed to when weights change. Reads the
+     * subject's exposures once per request from the lucid sink's table. Default `false`.
+     */
+    sticky?: boolean;
+    /** Events older than this (days) are pruned from the `db` transport once every sink has them. Default 30. */
+    retentionDays?: number;
+    /** Who may change flags (console, commands, admin API). */
+    authorize?: AdminAuthorizer;
+    /** Environments whose changes need a second person's approval. */
+    approvals?: ApprovalsConfig;
+    /** Create the tables at boot. Default `true` (the ecosystem convention). */
+    autoCreateSchema?: boolean;
+    /** Postgres: partition the event log by month. Default `false`. Decide before first boot. */
+    partitionEvents?: boolean;
+    /** Push ruleset changes to browsers through `@adonisjs/transmit`. Default `false`. */
+    realtime?: {
+        channel?: string;
+    } | boolean;
+}
+export interface StandaloneConfig<F extends Record<string, FlagDeclaration>> extends BaseConfig<F>, OwnedStateConfig {
+    topology?: 'standalone';
+}
+export interface ControlPlaneConfig<F extends Record<string, FlagDeclaration>> extends BaseConfig<F>, OwnedStateConfig {
+    topology: 'control-plane';
+    controlPlane: {
+        /** Route prefix. Default `/_flags`. */
+        prefix?: string;
+        /** Validates tenant tokens; derive the tenant from the token, never the body. */
+        verifyTenant: TenantVerifier;
+        /** Serve the OpenFeature Remote Evaluation Protocol. Default `true`. */
+        ofrep?: boolean;
+        /** Origins allowed to call OFREP from browsers. Default: none (no CORS headers). */
+        corsOrigins?: string[];
+    };
+}
+export interface TenantConfig<F extends Record<string, FlagDeclaration>> extends BaseConfig<F> {
+    topology: 'tenant';
+    /** The control-plane connection. */
+    tenant: {
+        url: string;
+        /** A token source (`tokens.clientCredentials(...)`) or a fixed secret. */
+        token: TokenSource | string;
+        /** This app's name on the control-plane. */
+        partition: string;
+        /** File for the last ruleset received (served when the control-plane is down at boot). */
+        snapshotPath?: string;
+        stream?: boolean;
+        intervalMs?: number;
+        capabilities?: string[];
+    };
+    /** FORBIDDEN on a tenant: it owns no state; everything lives on the control-plane. */
+    store?: never;
+    transport?: never;
+    sinks?: never;
+    analytics?: never;
+    approvals?: never;
+}
+export type FlagsConfig<F extends Record<string, FlagDeclaration> = Record<string, FlagDeclaration>> = StandaloneConfig<F> | ControlPlaneConfig<F> | TenantConfig<F>;
+/** Identity helper that types `config/flags.ts`. */
+export declare function defineConfig<const F extends Record<string, FlagDeclaration>>(config: FlagsConfig<F>): FlagsConfig<F>;
+export {};
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"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"}

package/dist/src/define_config.js

@@ -0,0 +1,90 @@
+import { ClickHouseBackend } from './analytics/clickhouse_backend.js';
+import { DuckDbBackend } from './analytics/duckdb.js';
+import { LucidBackend } from './analytics/lucid_backend.js';
+import { ClickHouseSink } from './sinks/clickhouse.js';
+import { LucidSink } from './sinks/lucid_sink.js';
+import { ParquetSink } from './sinks/parquet_sink.js';
+import { PostHogSink } from './sinks/posthog_sink.js';
+import { CallbackSink, MemorySink } from './sinks/sink.js';
+import { LucidStore } from './stores/lucid_store.js';
+import { MemoryStore } from './stores/memory_store.js';
+import { DbTransport } from './transports/db_transport.js';
+import { MemoryTransport } from './transports/memory_transport.js';
+import { RedisTransport, } from './transports/redis_transport.js';
+export const stores = {
+    /** The ruleset in your database (Postgres, MySQL, SQLite). The default. */
+    lucid(options = {}) {
+        return async (ctx) => new LucidStore(await ctx.db(options.connection), {
+            autoCreateSchema: ctx.autoCreateSchema,
+            partitionEvents: ctx.partitionEvents,
+        });
+    },
+    /** In process memory: tests and local development. */
+    memory(seed) {
+        return () => new MemoryStore(seed);
+    },
+};
+export const transports = {
+    /** The event log in your database. Transactional; the default when the store is `lucid`. */
+    db(options = {}) {
+        return async (ctx) => new DbTransport(await ctx.db(options.connection), {
+            autoCreateSchema: ctx.autoCreateSchema,
+            partitionEvents: ctx.partitionEvents,
+            ...options,
+        });
+    },
+    /** Redis Streams through `@adonisjs/redis`. */
+    redis(options = {}) {
+        return async (ctx) => new RedisTransport(await ctx.redis(options.connection), options);
+    },
+    /** In process memory: tests and local development. */
+    memory() {
+        return () => new MemoryTransport();
+    },
+};
+export const sinks = {
+    /** Analysis tables in your database (`flags_exposures`, `flags_tracks`); read by `analytics.lucid()`. */
+    lucid(options = {}) {
+        return async (ctx) => new LucidSink(await ctx.db(options.connection), {
+            autoCreateSchema: ctx.autoCreateSchema,
+            ...(options.batchSize !== undefined ? { batchSize: options.batchSize } : {}),
+            ...(options.intervalMs !== undefined ? { intervalMs: options.intervalMs } : {}),
+        });
+    },
+    posthog(options) {
+        return () => new PostHogSink(options);
+    },
+    clickhouse(options) {
+        return () => new ClickHouseSink(options);
+    },
+    /** Parquet files through DuckDB (`@duckdb/node-api`); read by `analytics.duckdb()`. */
+    parquet(options) {
+        return () => new ParquetSink(options);
+    },
+    /** Your function receives every batch. Must be idempotent by `event.id`. */
+    callback(fn, options = {}) {
+        return () => new CallbackSink(fn, options.batchSize, options.intervalMs);
+    },
+    memory() {
+        return () => new MemorySink();
+    },
+};
+export const analytics = {
+    lucid(options = {}) {
+        return async (ctx) => new LucidBackend(await ctx.db(options.connection));
+    },
+    duckdb(options) {
+        return () => new DuckDbBackend(options);
+    },
+    clickhouse(options) {
+        return () => new ClickHouseBackend(options);
+    },
+};
+/** Identity helper that types `config/flags.ts`. */
+export function defineConfig(config) {
+    if (config.topology === 'tenant' && config.role === 'worker') {
+        throw new Error('[flags] role "worker" makes no sense on a tenant: it has no relay; the control-plane fans events out');
+    }
+    return config;
+}
+//# sourceMappingURL=define_config.js.map

package/dist/src/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"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"}

package/dist/src/durable.d.ts

@@ -0,0 +1,29 @@
+import type { FlagsRuntime } from './runtime.js';
+/** The slice of `@adonis-agora/durable`'s engine this package uses. */
+export interface DurableEngineLike {
+    register(name: string, version: string, fn: (ctx: unknown, input: never) => Promise<void>, opts?: {
+        origin?: string;
+    }): void;
+    registerSchedules?(schedules: Array<{
+        key: string;
+        workflow: string;
+        input?: unknown;
+        everyMs: number;
+        overlap?: 'allow' | 'skip';
+    }>): void;
+}
+export declare const PACKAGE_ORIGIN = "@adonis-agora/flags";
+export declare const WORKFLOWS: {
+    readonly relay: 'flags.relay';
+    readonly schedules: 'flags.schedules';
+    readonly results: 'flags.results';
+    readonly maintenance: 'flags.maintenance';
+};
+/**
+ * Runs the background work as durable workflows: one schedule per sink for the relay, plus
+ * scheduled changes, results and maintenance. `overlap: 'skip'` keeps a slow run from piling up, and
+ * the durable console shows every run, its errors and retries. The leases and claims inside each
+ * task still make concurrent runs safe.
+ */
+export declare function registerDurableWorkflows(engine: DurableEngineLike, runtime: FlagsRuntime): boolean;
+//# sourceMappingURL=durable.d.ts.map

package/dist/src/durable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../../src/durable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,EACjD,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,IAAI,CAAC;IACR,iBAAiB,CAAC,CAChB,SAAS,EAAE,KAAK,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC5B,CAAC,GACD,IAAI,CAAC;CACT;AAED,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD,eAAO,MAAM,SAAS;aACpB,KAAK,EAAE,aAAa;aACpB,SAAS,EAAE,iBAAiB;aAC5B,OAAO,EAAE,eAAe;aACxB,WAAW,EAAE,mBAAmB;CACxB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,YAAY,GACpB,OAAO,CAgDT"}

package/dist/src/durable.js

@@ -0,0 +1,55 @@
+export const PACKAGE_ORIGIN = '@adonis-agora/flags';
+export const WORKFLOWS = {
+    relay: 'flags.relay',
+    schedules: 'flags.schedules',
+    results: 'flags.results',
+    maintenance: 'flags.maintenance',
+};
+/**
+ * Runs the background work as durable workflows: one schedule per sink for the relay, plus
+ * scheduled changes, results and maintenance. `overlap: 'skip'` keeps a slow run from piling up, and
+ * the durable console shows every run, its errors and retries. The leases and claims inside each
+ * task still make concurrent runs safe.
+ */
+export function registerDurableWorkflows(engine, runtime) {
+    const worker = runtime.worker;
+    if (!worker)
+        return false;
+    if (!engine.registerSchedules)
+        return false;
+    const opts = { origin: PACKAGE_ORIGIN };
+    engine.register(WORKFLOWS.relay, '1', async (_ctx, input) => {
+        const result = await worker.relaySink(input.sink);
+        if (result?.error)
+            throw new Error(result.error);
+    }, opts);
+    engine.register(WORKFLOWS.schedules, '1', async () => void (await worker.runSchedules()), opts);
+    engine.register(WORKFLOWS.results, '1', async () => void (await worker.computeAllResults()), opts);
+    engine.register(WORKFLOWS.maintenance, '1', async () => worker.maintenance(), opts);
+    const config = runtime.config;
+    const relayInterval = config.relay?.intervalMs ?? 5000;
+    engine.registerSchedules([
+        ...(runtime.relay?.sinkNames ?? []).map((sink) => ({
+            key: `flags.relay.${sink}`,
+            workflow: WORKFLOWS.relay,
+            input: { sink },
+            everyMs: Math.max(1000, runtime.sinks.get(sink)?.intervalMs ?? relayInterval),
+            overlap: 'skip',
+        })),
+        { key: 'flags.schedules', workflow: WORKFLOWS.schedules, everyMs: 15_000, overlap: 'skip' },
+        {
+            key: 'flags.results',
+            workflow: WORKFLOWS.results,
+            everyMs: config.resultsIntervalMs ?? 600_000,
+            overlap: 'skip',
+        },
+        {
+            key: 'flags.maintenance',
+            workflow: WORKFLOWS.maintenance,
+            everyMs: 3_600_000,
+            overlap: 'skip',
+        },
+    ]);
+    return true;
+}
+//# sourceMappingURL=durable.js.map

package/dist/src/durable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable.js","sourceRoot":"","sources":["../../src/durable.ts"],"names":[],"mappings":"AAqBA,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEpD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,KAAK,EAAE,aAAa;IACpB,SAAS,EAAE,iBAAiB;IAC5B,OAAO,EAAE,eAAe;IACxB,WAAW,EAAE,mBAAmB;CACxB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAyB,EACzB,OAAqB;IAErB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,iBAAiB;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACxC,MAAM,CAAC,QAAQ,CACb,SAAS,CAAC,KAAK,EACf,GAAG,EACH,KAAK,EAAE,IAAI,EAAE,KAAY,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAE,KAA0B,CAAC,IAAI,CAAC,CAAC;QACxE,IAAI,MAAM,EAAE,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC,EACD,IAAI,CACL,CAAC;IACF,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAChG,MAAM,CAAC,QAAQ,CACb,SAAS,CAAC,OAAO,EACjB,GAAG,EACH,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,MAAM,CAAC,iBAAiB,EAAE,CAAC,EACnD,IAAI,CACL,CAAC;IACF,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;IAEpF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAyE,CAAC;IACjG,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,IAAI,CAAC;IACvD,MAAM,CAAC,iBAAiB,CAAC;QACvB,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACjD,GAAG,EAAE,eAAe,IAAI,EAAE;YAC1B,QAAQ,EAAE,SAAS,CAAC,KAAK;YACzB,KAAK,EAAE,EAAE,IAAI,EAAE;YACf,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,IAAI,aAAa,CAAC;YAC7E,OAAO,EAAE,MAAe;SACzB,CAAC,CAAC;QACH,EAAE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;QAC3F;YACE,GAAG,EAAE,eAAe;YACpB,QAAQ,EAAE,SAAS,CAAC,OAAO;YAC3B,OAAO,EAAE,MAAM,CAAC,iBAAiB,IAAI,OAAO;YAC5C,OAAO,EAAE,MAAM;SAChB;QACD;YACE,GAAG,EAAE,mBAAmB;YACxB,QAAQ,EAAE,SAAS,CAAC,WAAW;YAC/B,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE,MAAM;SAChB;KACF,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/enrichers.d.ts

@@ -0,0 +1,51 @@
+import type { EvaluationContext, EvaluationDetails } from '@adonis-agora/flags-core';
+import type { FlagEvent } from './events/event.js';
+/**
+ * Synchronous hooks around evaluation (DESIGN §8): they attach flag state to whatever the request is
+ * already reporting — a span, an error report, the telescope timeline. They never block and never
+ * throw into the caller.
+ */
+export interface Enricher {
+    readonly name: string;
+    setup?(): Promise<void>;
+    onEvaluation?(details: EvaluationDetails, context: EvaluationContext): void;
+    onEvent?(event: FlagEvent): void;
+}
+/** Channel names, following the ecosystem's `agora:<lib>:<event>` convention. */
+export declare const DIAGNOSTICS_CHANNELS: {
+    readonly evaluation: 'agora:flags:evaluation';
+    readonly exposure: 'agora:flags:exposure';
+    readonly track: 'agora:flags:track';
+    readonly change: 'agora:flags:change';
+};
+interface SentryLike {
+    getClient?(): {
+        getIntegrationByName?(name: string): unknown;
+    } | undefined;
+    getCurrentScope?(): {
+        setTag?(key: string, value: string): void;
+    } | undefined;
+}
+export declare const enrichers: {
+    /**
+     * Publishes evaluations, exposures and tracks on `node:diagnostics_channel` (`agora:flags:*`):
+     * `@adonis-agora/diagnostics` and telescope pick them up. Free when nobody subscribes.
+     */
+    diagnostics(): Enricher;
+    /**
+     * OpenTelemetry: a `feature_flag.evaluation` event on the active span, with the semantic
+     * convention attributes (`feature_flag.key`, `feature_flag.result.variant`, …). Needs
+     * `@opentelemetry/api` (optional peer); without it this enricher does nothing.
+     */
+    otel(): Enricher;
+    /**
+     * Sentry: records each evaluated flag on the current scope, so an error report lists the flags
+     * the request saw. Pass your Sentry module: `enrichers.sentry(Sentry)`. Uses Sentry's
+     * feature-flags integration when it is installed, and a `flag.<key>` tag otherwise.
+     */
+    sentry(sentry: SentryLike): Enricher;
+};
+/** Runs enrichers without ever letting one break evaluation. */
+export declare function runEnrichers(list: Enricher[], fn: (enricher: Enricher) => void): void;
+export {};
+//# sourceMappingURL=enrichers.d.ts.map

package/dist/src/enrichers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichers.d.ts","sourceRoot":"","sources":["../../src/enrichers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC5E,OAAO,CAAC,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CAClC;AAED,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;aAC/B,UAAU,EAAE,wBAAwB;aACpC,QAAQ,EAAE,sBAAsB;aAChC,KAAK,EAAE,mBAAmB;aAC1B,MAAM,EAAE,oBAAoB;CACpB,CAAC;AAEX,UAAU,UAAU;IAClB,SAAS,CAAC,IAAI;QAAE,oBAAoB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC3E,eAAe,CAAC,IAAI;QAAE,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,SAAS,CAAC;CAC/E;AAUD,eAAO,MAAM,SAAS;IACpB;;;OAGG;IACH,WAAW,IAAI,QAAQ;IAwBvB;;;;OAIG;IACH,IAAI,IAAI,QAAQ;IA6BhB;;;;OAIG;IACH,MAAM,SAAS,UAAU,GAAG,QAAQ;CAiBrC,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAQrF"}