@beignet/core 0.0.12 → 0.0.14

package/dist/flags/index.d.ts

@@ -0,0 +1,293 @@
+/**
+ * @beignet/core/flags
+ *
+ * Provider-neutral feature flag primitives for Beignet applications.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * JSON-compatible value used by object flags and flag metadata.
+ */
+export type FlagJsonValue = null | boolean | number | string | readonly FlagJsonValue[] | {
+    readonly [key: string]: FlagJsonValue;
+};
+/**
+ * Object-valued flags intentionally exclude scalar JSON values so the flag
+ * kind remains predictable.
+ */
+export type FlagObjectValue = readonly FlagJsonValue[] | {
+    readonly [key: string]: FlagJsonValue;
+};
+/**
+ * Value kinds supported by Beignet flags.
+ */
+export type FlagValue = boolean | string | number | FlagObjectValue;
+/**
+ * Stable feature flag key.
+ */
+export type FlagKey = string;
+/**
+ * Feature flag value kind.
+ */
+export type FlagKind = "boolean" | "string" | "number" | "object";
+/**
+ * Subject used for provider-neutral flag targeting.
+ */
+export type FlagSubject = {
+    type: string;
+    id: string;
+};
+/**
+ * Tenant or account used for provider-neutral flag targeting.
+ */
+export type FlagTenant = {
+    id: string;
+    slug?: string;
+};
+/**
+ * Attribute value accepted by the provider-neutral flag context.
+ */
+export type FlagAttributeValue = null | boolean | number | string | readonly FlagAttributeValue[] | {
+    readonly [key: string]: FlagAttributeValue;
+};
+/**
+ * Context supplied to flag evaluations, exposure recording, and tracking.
+ */
+export type FlagEvaluationContext = {
+    /**
+     * Stable key used by providers for rollout bucketing and targeting.
+     */
+    targetingKey: string;
+    /**
+     * Actor, user, service, tenant, or account being targeted.
+     */
+    subject?: FlagSubject;
+    /**
+     * Tenant/account scope, when available.
+     */
+    tenant?: FlagTenant;
+    /**
+     * Provider-neutral targeting attributes. Keep private data out unless the
+     * selected provider and retention policy are approved for it.
+     */
+    attributes?: Record<string, FlagAttributeValue>;
+    /**
+     * Attribute keys that should be treated as private by providers and
+     * instrumentation.
+     */
+    privateAttributes?: readonly string[];
+    requestId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceparent?: string;
+};
+/**
+ * Flag definition registered through `defineFlags(...)`.
+ */
+export type FlagDef<TValue extends FlagValue = FlagValue> = {
+    key: FlagKey;
+    kind: FlagKindForValue<TValue>;
+    defaultValue: TValue;
+    description?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Infer the flag value type from a flag definition.
+ */
+export type InferFlagValue<TFlag> = TFlag extends FlagDef<infer TValue> ? TValue : never;
+/**
+ * Map a value type to its runtime flag kind.
+ */
+export type FlagKindForValue<TValue extends FlagValue> = TValue extends boolean ? "boolean" : TValue extends string ? "string" : TValue extends number ? "number" : "object";
+/**
+ * Options accepted when declaring a flag.
+ */
+export type DefineFlagOptions<TValue extends FlagValue> = {
+    default: TValue;
+    description?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Registry returned by `defineFlags(...)`.
+ */
+export type FlagRegistry = Record<string, FlagDef>;
+/**
+ * Reason a flag received its value.
+ */
+export type FlagEvaluationReason = "static" | "targeting_match" | "default" | "error" | "unknown" | (string & {});
+/**
+ * Normalized error summary for failed flag provider evaluations.
+ */
+export type FlagEvaluationError = {
+    message: string;
+    code?: string;
+};
+/**
+ * Options accepted by flag evaluations.
+ */
+export type FlagEvaluationOptions<TValue extends FlagValue = FlagValue> = {
+    context?: FlagEvaluationContext;
+    /**
+     * Override the flag declaration default for this call.
+     */
+    defaultValue?: TValue;
+    /**
+     * Explicitly record an exposure after evaluation succeeds. Plain evaluation
+     * does not record exposure by default.
+     */
+    expose?: boolean;
+};
+/**
+ * Normalized flag evaluation details.
+ */
+export type FlagEvaluationDetails<TValue extends FlagValue = FlagValue> = {
+    key: string;
+    value: TValue;
+    defaultValue: TValue;
+    kind: FlagKindForValue<TValue>;
+    reason: FlagEvaluationReason;
+    defaulted: boolean;
+    variant?: string;
+    metadata?: Record<string, unknown>;
+    error?: FlagEvaluationError;
+};
+/**
+ * Options accepted by explicit exposure recording.
+ */
+export type FlagExposureOptions = {
+    context?: FlagEvaluationContext;
+    value?: FlagValue;
+    variant?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Options accepted by tracking calls.
+ */
+export type FlagTrackOptions = {
+    context?: FlagEvaluationContext;
+    value?: number;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * App-facing feature flag port.
+ */
+export type FlagsPort = {
+    evaluate<TValue extends FlagValue>(flag: FlagDef<TValue>, options?: FlagEvaluationOptions<TValue>): Promise<TValue>;
+    details<TValue extends FlagValue>(flag: FlagDef<TValue>, options?: FlagEvaluationOptions<TValue>): Promise<FlagEvaluationDetails<TValue>>;
+    recordExposure<TValue extends FlagValue>(flag: FlagDef<TValue>, options?: FlagExposureOptions): Promise<void>;
+    track(event: string, options?: FlagTrackOptions): Promise<void>;
+};
+/**
+ * Flag evaluation observation emitted by memory/static adapters.
+ */
+export type FlagEvaluationObservation<TValue extends FlagValue = FlagValue> = {
+    source: "evaluate" | "details";
+    flag: FlagDef<TValue>;
+    context?: FlagEvaluationContext;
+    details: FlagEvaluationDetails<TValue>;
+    durationMs: number;
+    requestId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceparent?: string;
+};
+/**
+ * Explicit flag exposure observation.
+ */
+export type FlagExposureObservation<TValue extends FlagValue = FlagValue> = {
+    flag: FlagDef<TValue>;
+    context?: FlagEvaluationContext;
+    value?: FlagValue;
+    variant?: string;
+    metadata?: Record<string, unknown>;
+    requestId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceparent?: string;
+};
+/**
+ * Flag tracking observation.
+ */
+export type FlagTrackObservation = {
+    event: string;
+    context?: FlagEvaluationContext;
+    value?: number;
+    metadata?: Record<string, unknown>;
+    requestId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    traceparent?: string;
+};
+export type FlagEvaluationObserver = (observation: FlagEvaluationObservation) => MaybePromise<void>;
+export type FlagExposureObserver = (observation: FlagExposureObservation) => MaybePromise<void>;
+export type FlagTrackObserver = (observation: FlagTrackObservation) => MaybePromise<void>;
+/**
+ * Options for memory/static flag adapters.
+ */
+export type CreateFlagsOptions = {
+    onEvaluation?: FlagEvaluationObserver;
+    onExposure?: FlagExposureObserver;
+    onTrack?: FlagTrackObserver;
+};
+/**
+ * Static flag values keyed by flag key.
+ */
+export type StaticFlagValues = Record<string, FlagValue>;
+/**
+ * Options for `createStaticFlags(...)`.
+ */
+export type CreateStaticFlagsOptions = CreateFlagsOptions & {
+    values?: StaticFlagValues;
+};
+/**
+ * In-memory flags port with mutation helpers for tests and local development.
+ */
+export type MemoryFlagsPort = FlagsPort & {
+    values: Map<string, FlagValue>;
+    set<TValue extends FlagValue>(flag: FlagDef<TValue>, value: TValue): void;
+    reset(flag?: FlagDef): void;
+};
+declare function defineBooleanFlag(key: string, options: DefineFlagOptions<boolean>): FlagDef<boolean>;
+declare function defineStringFlag(key: string, options: DefineFlagOptions<string>): FlagDef<string>;
+declare function defineStringFlag<const TValue extends string>(key: string, options: DefineFlagOptions<TValue>): FlagDef<TValue>;
+declare function defineNumberFlag(key: string, options: DefineFlagOptions<number>): FlagDef<number>;
+declare function defineNumberFlag<const TValue extends number>(key: string, options: DefineFlagOptions<TValue>): FlagDef<TValue>;
+declare function defineObjectFlag<TValue extends FlagObjectValue>(key: string, options: DefineFlagOptions<TValue>): FlagDef<TValue>;
+/**
+ * Define one feature flag declaration.
+ */
+export declare const defineFlag: {
+    boolean: typeof defineBooleanFlag;
+    string: typeof defineStringFlag;
+    number: typeof defineNumberFlag;
+    object: typeof defineObjectFlag;
+};
+/**
+ * Define a typed registry of feature flags.
+ */
+export declare function defineFlags<const TRegistry extends FlagRegistry>(registry: TRegistry): TRegistry;
+/**
+ * Alias for apps that prefer to name the collection explicitly.
+ */
+export declare const defineFlagRegistry: typeof defineFlags;
+/**
+ * Evaluate a flag through any `FlagsPort`.
+ */
+export declare function evaluateFlag<TValue extends FlagValue>(flags: FlagsPort, flag: FlagDef<TValue>, options?: FlagEvaluationOptions<TValue>): Promise<TValue>;
+/**
+ * Return detailed flag evaluation information through any `FlagsPort`.
+ */
+export declare function getFlagDetails<TValue extends FlagValue>(flags: FlagsPort, flag: FlagDef<TValue>, options?: FlagEvaluationOptions<TValue>): Promise<FlagEvaluationDetails<TValue>>;
+/**
+ * Create static flags backed by fixed values.
+ */
+export declare function createStaticFlags(options?: CreateStaticFlagsOptions): FlagsPort;
+/**
+ * Create mutable in-memory flags for tests, examples, and local development.
+ */
+export declare function createMemoryFlags(options?: CreateStaticFlagsOptions): MemoryFlagsPort;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/flags/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flags/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,aAAa,EAAE,GACxB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,aAAa,EAAE,GACxB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,kBAAkB,EAAE,GAC7B;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAAA;CAAE,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;OAEG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAChD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,OAAO,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS,IAAI;IAC1D,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAC9B,KAAK,SAAS,OAAO,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,MAAM,SAAS,SAAS,IAAI,MAAM,SAAS,OAAO,GAC3E,SAAS,GACT,MAAM,SAAS,MAAM,GACnB,QAAQ,GACR,MAAM,SAAS,MAAM,GACnB,QAAQ,GACR,QAAQ,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,SAAS,IAAI;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,iBAAiB,GACjB,SAAS,GACT,OAAO,GACP,SAAS,GACT,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS,IAAI;IACxE,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS,IAAI;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,SAAS,SAAS,EAC/B,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EACrB,OAAO,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACtC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,OAAO,CAAC,MAAM,SAAS,SAAS,EAC9B,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EACrB,OAAO,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACtC,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1C,cAAc,CAAC,MAAM,SAAS,SAAS,EACrC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EACrB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,yBAAyB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS,IAAI;IAC5E,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS,IAAI;IAC1E,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,CACnC,WAAW,EAAE,yBAAyB,KACnC,YAAY,CAAC,IAAI,CAAC,CAAC;AAExB,MAAM,MAAM,oBAAoB,GAAG,CACjC,WAAW,EAAE,uBAAuB,KACjC,YAAY,CAAC,IAAI,CAAC,CAAC;AAExB,MAAM,MAAM,iBAAiB,GAAG,CAC9B,WAAW,EAAE,oBAAoB,KAC9B,YAAY,CAAC,IAAI,CAAC,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG;IAC1D,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG;IACxC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC/B,GAAG,CAAC,MAAM,SAAS,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1E,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B,CAAC;AAuBF,iBAAS,iBAAiB,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAClC,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,iBAAS,gBAAgB,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAAC;AACnB,iBAAS,gBAAgB,CAAC,KAAK,CAAC,MAAM,SAAS,MAAM,EACnD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAAC;AAQnB,iBAAS,gBAAgB,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAAC;AACnB,iBAAS,gBAAgB,CAAC,KAAK,CAAC,MAAM,SAAS,MAAM,EACnD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAAC;AAQnB,iBAAS,gBAAgB,CAAC,MAAM,SAAS,eAAe,EACtD,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;CAKtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,SAAS,SAAS,YAAY,EAC9D,QAAQ,EAAE,SAAS,GAClB,SAAS,CAEX;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,oBAAc,CAAC;AAE9C;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,SAAS,EACnD,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EACrB,OAAO,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACtC,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,SAAS,SAAS,EACrD,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EACrB,OAAO,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACtC,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAExC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,SAAS,CAEX;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,eAAe,CAyBjB"}

package/dist/flags/index.js

@@ -0,0 +1,204 @@
+/**
+ * @beignet/core/flags
+ *
+ * Provider-neutral feature flag primitives for Beignet applications.
+ */
+function createFlag(kind, key, options) {
+    const defaultValue = options.default;
+    if (!matchesKind(defaultValue, kind)) {
+        throw new Error(`Flag "${key}" default value does not match "${kind}" flag kind.`);
+    }
+    return {
+        key,
+        kind: kind,
+        defaultValue,
+        description: options.description,
+        metadata: options.metadata,
+    };
+}
+function defineBooleanFlag(key, options) {
+    return createFlag("boolean", key, options);
+}
+function defineStringFlag(key, options) {
+    return createFlag("string", key, options);
+}
+function defineNumberFlag(key, options) {
+    return createFlag("number", key, options);
+}
+function defineObjectFlag(key, options) {
+    return createFlag("object", key, options);
+}
+/**
+ * Define one feature flag declaration.
+ */
+export const defineFlag = {
+    boolean: defineBooleanFlag,
+    string: defineStringFlag,
+    number: defineNumberFlag,
+    object: defineObjectFlag,
+};
+/**
+ * Define a typed registry of feature flags.
+ */
+export function defineFlags(registry) {
+    return registry;
+}
+/**
+ * Alias for apps that prefer to name the collection explicitly.
+ */
+export const defineFlagRegistry = defineFlags;
+/**
+ * Evaluate a flag through any `FlagsPort`.
+ */
+export function evaluateFlag(flags, flag, options) {
+    return flags.evaluate(flag, options);
+}
+/**
+ * Return detailed flag evaluation information through any `FlagsPort`.
+ */
+export function getFlagDetails(flags, flag, options) {
+    return flags.details(flag, options);
+}
+/**
+ * Create static flags backed by fixed values.
+ */
+export function createStaticFlags(options = {}) {
+    return createFlagsFromStore(() => options.values ?? {}, options);
+}
+/**
+ * Create mutable in-memory flags for tests, examples, and local development.
+ */
+export function createMemoryFlags(options = {}) {
+    const values = new Map(Object.entries(options.values ?? {}));
+    const port = createFlagsFromStore(() => Object.fromEntries(values), options);
+    return {
+        ...port,
+        values,
+        set(flag, value) {
+            if (!matchesKind(value, flag.kind)) {
+                throw new Error(`Flag "${flag.key}" value does not match "${flag.kind}" flag kind.`);
+            }
+            values.set(flag.key, value);
+        },
+        reset(flag) {
+            if (flag) {
+                values.delete(flag.key);
+                return;
+            }
+            values.clear();
+        },
+    };
+}
+function createFlagsFromStore(readValues, observers) {
+    async function resolve(flag, options, source) {
+        const startedAt = Date.now();
+        const defaultValue = options?.defaultValue ?? flag.defaultValue;
+        const values = readValues();
+        const stored = values[flag.key];
+        const hasStored = Object.hasOwn(values, flag.key);
+        const usedStoredValue = hasStored && matchesKind(stored, flag.kind);
+        const value = usedStoredValue
+            ? stored
+            : defaultValue;
+        const details = {
+            key: flag.key,
+            kind: flag.kind,
+            value,
+            defaultValue,
+            reason: usedStoredValue ? "static" : "default",
+            defaulted: !usedStoredValue,
+        };
+        await observeEvaluation(observers.onEvaluation, {
+            source,
+            flag,
+            context: options?.context,
+            details,
+            durationMs: Date.now() - startedAt,
+            ...correlationFromContext(options?.context),
+        });
+        if (options?.expose) {
+            await flags.recordExposure(flag, {
+                context: options.context,
+                value: details.value,
+                variant: details.variant,
+                metadata: details.metadata,
+            });
+        }
+        return details;
+    }
+    const flags = {
+        async evaluate(flag, options) {
+            const details = await resolve(flag, options, "evaluate");
+            return details.value;
+        },
+        async details(flag, options) {
+            return resolve(flag, options, "details");
+        },
+        async recordExposure(flag, options) {
+            await observeExposure(observers.onExposure, {
+                flag,
+                context: options?.context,
+                value: options?.value,
+                variant: options?.variant,
+                metadata: options?.metadata,
+                ...correlationFromContext(options?.context),
+            });
+        },
+        async track(event, options) {
+            await observeTrack(observers.onTrack, {
+                event,
+                context: options?.context,
+                value: options?.value,
+                metadata: options?.metadata,
+                ...correlationFromContext(options?.context),
+            });
+        },
+    };
+    return flags;
+}
+function matchesKind(value, kind) {
+    switch (kind) {
+        case "boolean":
+            return typeof value === "boolean";
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "object":
+            return typeof value === "object" && value !== null;
+    }
+}
+function correlationFromContext(context) {
+    return {
+        requestId: context?.requestId,
+        traceId: context?.traceId,
+        spanId: context?.spanId,
+        parentSpanId: context?.parentSpanId,
+        traceparent: context?.traceparent,
+    };
+}
+async function observeEvaluation(observer, observation) {
+    try {
+        await observer?.(observation);
+    }
+    catch {
+        // Observers are diagnostic only.
+    }
+}
+async function observeExposure(observer, observation) {
+    try {
+        await observer?.(observation);
+    }
+    catch {
+        // Observers are diagnostic only.
+    }
+}
+async function observeTrack(observer, observation) {
+    try {
+        await observer?.(observation);
+    }
+    catch {
+        // Observers are diagnostic only.
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/flags/index.js.map

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

package/dist/locks/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @beignet/core/locks
+ *
+ * Provider-neutral distributed lock and lease primitives for Beignet apps.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Metadata attached to lock acquisition instrumentation and diagnostics.
+ */
+export type LeaseMetadata = Record<string, string | number | boolean | null | undefined>;
+/**
+ * Options for acquiring a lease.
+ */
+export type LeaseAcquireOptions = {
+    /**
+     * Lease time-to-live in milliseconds. The provider must treat ownership as
+     * expired after this duration unless the lease is renewed.
+     */
+    ttlMs: number;
+    /**
+     * How long to wait for the lease before returning a non-acquired result.
+     *
+     * @default 0
+     */
+    waitMs?: number;
+    /**
+     * Delay between acquisition attempts while waiting.
+     *
+     * @default 50
+     */
+    retryDelayMs?: number;
+    /**
+     * Optional owner token supplied by the caller. Providers generate one when
+     * omitted. Release and renew operations must only succeed for the current
+     * owner token.
+     */
+    ownerToken?: string;
+    /**
+     * Optional diagnostics metadata. Providers should not use this for lock
+     * correctness.
+     */
+    metadata?: LeaseMetadata;
+};
+/**
+ * Options for renewing a lease.
+ */
+export type LeaseRenewOptions = {
+    /**
+     * New lease time-to-live in milliseconds. Defaults to the original ttlMs
+     * used to acquire the lease.
+     */
+    ttlMs?: number;
+};
+/**
+ * Active lease handle returned by a lock provider.
+ */
+export type LeaseHandle = {
+    key: string;
+    ownerToken: string;
+    expiresAt?: Date;
+    /**
+     * Optional monotonically increasing token. Apps can store this with writes to
+     * reject stale lease owners when the underlying resource supports fencing.
+     */
+    fencingToken?: string | number;
+    renew(options?: LeaseRenewOptions): Promise<boolean>;
+    release(): Promise<boolean>;
+};
+/**
+ * Lease acquisition result.
+ */
+export type LeaseAcquireResult = {
+    acquired: true;
+    lease: LeaseHandle;
+} | {
+    acquired: false;
+    reason: "unavailable" | "timeout";
+};
+/**
+ * App-facing lock port.
+ */
+export type LocksPort = {
+    acquire(key: string, options: LeaseAcquireOptions): Promise<LeaseAcquireResult>;
+    withLease<T>(key: string, options: LeaseAcquireOptions, fn: (ctx: {
+        lease: LeaseHandle;
+    }) => MaybePromise<T>): Promise<T | undefined>;
+    restore(key: string, ownerToken: string): LeaseHandle;
+    forceRelease(key: string): Promise<boolean>;
+};
+/**
+ * Captured memory lease state exposed for tests.
+ */
+export type MemoryLeaseRecord = {
+    key: string;
+    ownerToken: string;
+    expiresAt: Date;
+    ttlMs: number;
+    fencingToken: number;
+    metadata?: LeaseMetadata;
+};
+/**
+ * In-memory locks port exposed for assertions in tests.
+ */
+export type MemoryLocksPort = LocksPort & {
+    leases: Map<string, MemoryLeaseRecord>;
+    reset(): void;
+};
+/**
+ * Options for the in-memory locks adapter.
+ */
+export type CreateMemoryLocksOptions = {
+    now?: () => Date;
+    createOwnerToken?: () => string;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Options for the in-memory locks provider.
+ */
+export type MemoryLocksProviderOptions = CreateMemoryLocksOptions & {
+    name?: string;
+};
+/**
+ * Ports contributed by the memory locks provider.
+ */
+export interface MemoryLocksProviderPorts {
+    locks: LocksPort;
+}
+/**
+ * Error thrown when a lease option is invalid.
+ */
+export declare class LeaseOptionsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Create an in-memory locks port for tests and single-process development.
+ */
+export declare function createMemoryLocks(options?: CreateMemoryLocksOptions): MemoryLocksPort;
+/**
+ * Create a provider that contributes an in-memory locks port.
+ */
+export declare function createMemoryLocksProvider(options?: MemoryLocksProviderOptions): import("../providers/provider.js").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    locks: LocksPort;
+}, unknown, void>;
+/**
+ * Convenience helper for any lock port.
+ */
+export declare function acquireLease(locks: LocksPort, key: string, options: LeaseAcquireOptions): Promise<LeaseAcquireResult>;
+/**
+ * Convenience helper for any lock port.
+ */
+export declare function withLease<T>(locks: LocksPort, key: string, options: LeaseAcquireOptions, fn: (ctx: {
+    lease: LeaseHandle;
+}) => MaybePromise<T>): Promise<T | undefined>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/locks/index.d.ts.map

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