@contractspec/lib.feature-flags 0.0.0-canary-20260113162409

package/dist/entities/index.js

@@ -0,0 +1,325 @@
+import { defineEntity, defineEntityEnum, field, index } from "@contractspec/lib.schema";
+
+//#region src/entities/index.ts
+/**
+* Feature flag status enum.
+*/
+const FlagStatusEnum = defineEntityEnum({
+	name: "FlagStatus",
+	values: [
+		"OFF",
+		"ON",
+		"GRADUAL"
+	],
+	schema: "lssm_feature_flags",
+	description: "Status of a feature flag."
+});
+/**
+* Targeting rule operator enum.
+*/
+const RuleOperatorEnum = defineEntityEnum({
+	name: "RuleOperator",
+	values: [
+		"EQ",
+		"NEQ",
+		"IN",
+		"NIN",
+		"CONTAINS",
+		"NOT_CONTAINS",
+		"GT",
+		"GTE",
+		"LT",
+		"LTE",
+		"PERCENTAGE"
+	],
+	schema: "lssm_feature_flags",
+	description: "Operator for targeting rule conditions."
+});
+/**
+* Experiment status enum.
+*/
+const ExperimentStatusEnum = defineEntityEnum({
+	name: "ExperimentStatus",
+	values: [
+		"DRAFT",
+		"RUNNING",
+		"PAUSED",
+		"COMPLETED",
+		"CANCELLED"
+	],
+	schema: "lssm_feature_flags",
+	description: "Status of an experiment."
+});
+/**
+* FeatureFlag entity - defines a feature flag.
+*/
+const FeatureFlagEntity = defineEntity({
+	name: "FeatureFlag",
+	description: "A feature flag for controlling feature availability.",
+	schema: "lssm_feature_flags",
+	map: "feature_flag",
+	fields: {
+		id: field.id({ description: "Unique flag identifier" }),
+		key: field.string({
+			isUnique: true,
+			description: "Flag key (e.g., new_dashboard)"
+		}),
+		name: field.string({ description: "Human-readable name" }),
+		description: field.string({
+			isOptional: true,
+			description: "Description of the flag"
+		}),
+		status: field.enum("FlagStatus", {
+			default: "OFF",
+			description: "Flag status"
+		}),
+		defaultValue: field.boolean({
+			default: false,
+			description: "Default value when no rules match"
+		}),
+		variants: field.json({
+			isOptional: true,
+			description: "Variant definitions for multivariate flags"
+		}),
+		orgId: field.string({
+			isOptional: true,
+			description: "Organization scope (null = global)"
+		}),
+		tags: field.json({
+			isOptional: true,
+			description: "Tags for categorization"
+		}),
+		metadata: field.json({
+			isOptional: true,
+			description: "Additional metadata"
+		}),
+		createdAt: field.createdAt(),
+		updatedAt: field.updatedAt(),
+		targetingRules: field.hasMany("FlagTargetingRule"),
+		experiments: field.hasMany("Experiment"),
+		evaluations: field.hasMany("FlagEvaluation")
+	},
+	indexes: [index.on(["orgId", "key"]), index.on(["status"])],
+	enums: [FlagStatusEnum]
+});
+/**
+* FlagTargetingRule entity - conditions for targeting.
+*/
+const FlagTargetingRuleEntity = defineEntity({
+	name: "FlagTargetingRule",
+	description: "A targeting rule for conditional flag evaluation.",
+	schema: "lssm_feature_flags",
+	map: "flag_targeting_rule",
+	fields: {
+		id: field.id({ description: "Unique rule identifier" }),
+		flagId: field.foreignKey({ description: "Parent feature flag" }),
+		name: field.string({
+			isOptional: true,
+			description: "Rule name for debugging"
+		}),
+		priority: field.int({
+			default: 0,
+			description: "Rule priority (lower = higher priority)"
+		}),
+		enabled: field.boolean({
+			default: true,
+			description: "Whether rule is active"
+		}),
+		attribute: field.string({ description: "Target attribute (userId, orgId, plan, segment, etc.)" }),
+		operator: field.enum("RuleOperator", { description: "Comparison operator" }),
+		value: field.json({ description: "Target value(s)" }),
+		rolloutPercentage: field.int({
+			isOptional: true,
+			description: "Percentage for gradual rollout (0-100)"
+		}),
+		serveValue: field.boolean({
+			isOptional: true,
+			description: "Boolean value to serve"
+		}),
+		serveVariant: field.string({
+			isOptional: true,
+			description: "Variant key to serve (for multivariate)"
+		}),
+		createdAt: field.createdAt(),
+		updatedAt: field.updatedAt(),
+		flag: field.belongsTo("FeatureFlag", ["flagId"], ["id"], { onDelete: "Cascade" })
+	},
+	indexes: [index.on(["flagId", "priority"]), index.on(["attribute"])],
+	enums: [RuleOperatorEnum]
+});
+/**
+* Experiment entity - A/B test configuration.
+*/
+const ExperimentEntity = defineEntity({
+	name: "Experiment",
+	description: "An A/B test experiment.",
+	schema: "lssm_feature_flags",
+	map: "experiment",
+	fields: {
+		id: field.id({ description: "Unique experiment identifier" }),
+		key: field.string({
+			isUnique: true,
+			description: "Experiment key"
+		}),
+		name: field.string({ description: "Human-readable name" }),
+		description: field.string({
+			isOptional: true,
+			description: "Experiment description"
+		}),
+		hypothesis: field.string({
+			isOptional: true,
+			description: "Experiment hypothesis"
+		}),
+		flagId: field.foreignKey({ description: "Associated feature flag" }),
+		status: field.enum("ExperimentStatus", {
+			default: "DRAFT",
+			description: "Experiment status"
+		}),
+		variants: field.json({ description: "Variant definitions with split ratios" }),
+		metrics: field.json({
+			isOptional: true,
+			description: "Metrics to track"
+		}),
+		audiencePercentage: field.int({
+			default: 100,
+			description: "Percentage of audience to include"
+		}),
+		audienceFilter: field.json({
+			isOptional: true,
+			description: "Audience filter criteria"
+		}),
+		scheduledStartAt: field.dateTime({
+			isOptional: true,
+			description: "Scheduled start time"
+		}),
+		scheduledEndAt: field.dateTime({
+			isOptional: true,
+			description: "Scheduled end time"
+		}),
+		startedAt: field.dateTime({
+			isOptional: true,
+			description: "Actual start time"
+		}),
+		endedAt: field.dateTime({
+			isOptional: true,
+			description: "Actual end time"
+		}),
+		winningVariant: field.string({
+			isOptional: true,
+			description: "Declared winning variant"
+		}),
+		results: field.json({
+			isOptional: true,
+			description: "Experiment results summary"
+		}),
+		orgId: field.string({
+			isOptional: true,
+			description: "Organization scope"
+		}),
+		createdAt: field.createdAt(),
+		updatedAt: field.updatedAt(),
+		flag: field.belongsTo("FeatureFlag", ["flagId"], ["id"], { onDelete: "Cascade" }),
+		assignments: field.hasMany("ExperimentAssignment")
+	},
+	indexes: [
+		index.on(["status"]),
+		index.on(["orgId", "status"]),
+		index.on(["flagId"])
+	],
+	enums: [ExperimentStatusEnum]
+});
+/**
+* ExperimentAssignment entity - tracks which variant a subject is assigned to.
+*/
+const ExperimentAssignmentEntity = defineEntity({
+	name: "ExperimentAssignment",
+	description: "Tracks experiment variant assignments.",
+	schema: "lssm_feature_flags",
+	map: "experiment_assignment",
+	fields: {
+		id: field.id({ description: "Unique assignment identifier" }),
+		experimentId: field.foreignKey({ description: "Parent experiment" }),
+		subjectType: field.string({ description: "Subject type (user, org, session)" }),
+		subjectId: field.string({ description: "Subject identifier" }),
+		variant: field.string({ description: "Assigned variant key" }),
+		bucket: field.int({ description: "Hash bucket (0-99)" }),
+		context: field.json({
+			isOptional: true,
+			description: "Context at assignment time"
+		}),
+		assignedAt: field.dateTime({ description: "Assignment timestamp" }),
+		experiment: field.belongsTo("Experiment", ["experimentId"], ["id"], { onDelete: "Cascade" })
+	},
+	indexes: [index.unique([
+		"experimentId",
+		"subjectType",
+		"subjectId"
+	], { name: "experiment_assignment_unique" }), index.on(["subjectType", "subjectId"])]
+});
+/**
+* FlagEvaluation entity - evaluation log for analytics.
+*/
+const FlagEvaluationEntity = defineEntity({
+	name: "FlagEvaluation",
+	description: "Log of flag evaluations for debugging and analytics.",
+	schema: "lssm_feature_flags",
+	map: "flag_evaluation",
+	fields: {
+		id: field.id({ description: "Unique evaluation identifier" }),
+		flagId: field.foreignKey({ description: "Evaluated flag" }),
+		flagKey: field.string({ description: "Flag key (denormalized for queries)" }),
+		subjectType: field.string({ description: "Subject type (user, org, anonymous)" }),
+		subjectId: field.string({ description: "Subject identifier" }),
+		result: field.boolean({ description: "Evaluation result" }),
+		variant: field.string({
+			isOptional: true,
+			description: "Served variant (for multivariate)"
+		}),
+		matchedRuleId: field.string({
+			isOptional: true,
+			description: "Rule that matched (if any)"
+		}),
+		reason: field.string({ description: "Evaluation reason (default, rule, experiment, etc.)" }),
+		context: field.json({
+			isOptional: true,
+			description: "Evaluation context"
+		}),
+		evaluatedAt: field.dateTime({ description: "Evaluation timestamp" }),
+		flag: field.belongsTo("FeatureFlag", ["flagId"], ["id"], { onDelete: "Cascade" })
+	},
+	indexes: [
+		index.on(["flagKey", "evaluatedAt"]),
+		index.on([
+			"subjectType",
+			"subjectId",
+			"evaluatedAt"
+		]),
+		index.on(["flagId", "evaluatedAt"])
+	]
+});
+/**
+* All feature flag entities for schema composition.
+*/
+const featureFlagEntities = [
+	FeatureFlagEntity,
+	FlagTargetingRuleEntity,
+	ExperimentEntity,
+	ExperimentAssignmentEntity,
+	FlagEvaluationEntity
+];
+/**
+* Module schema contribution for feature flags.
+*/
+const featureFlagsSchemaContribution = {
+	moduleId: "@contractspec/lib.feature-flags",
+	entities: featureFlagEntities,
+	enums: [
+		FlagStatusEnum,
+		RuleOperatorEnum,
+		ExperimentStatusEnum
+	]
+};
+
+//#endregion
+export { ExperimentAssignmentEntity, ExperimentEntity, ExperimentStatusEnum, FeatureFlagEntity, FlagEvaluationEntity, FlagStatusEnum, FlagTargetingRuleEntity, RuleOperatorEnum, featureFlagEntities, featureFlagsSchemaContribution };
+//# sourceMappingURL=index.js.map

package/dist/entities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/entities/index.ts"],"sourcesContent":["import {\n  defineEntity,\n  defineEntityEnum,\n  field,\n  index,\n} from '@contractspec/lib.schema';\nimport type { ModuleSchemaContribution } from '@contractspec/lib.schema';\n\n/**\n * Feature flag status enum.\n */\nexport const FlagStatusEnum = defineEntityEnum({\n  name: 'FlagStatus',\n  values: ['OFF', 'ON', 'GRADUAL'] as const,\n  schema: 'lssm_feature_flags',\n  description: 'Status of a feature flag.',\n});\n\n/**\n * Targeting rule operator enum.\n */\nexport const RuleOperatorEnum = defineEntityEnum({\n  name: 'RuleOperator',\n  values: [\n    'EQ',\n    'NEQ',\n    'IN',\n    'NIN',\n    'CONTAINS',\n    'NOT_CONTAINS',\n    'GT',\n    'GTE',\n    'LT',\n    'LTE',\n    'PERCENTAGE',\n  ] as const,\n  schema: 'lssm_feature_flags',\n  description: 'Operator for targeting rule conditions.',\n});\n\n/**\n * Experiment status enum.\n */\nexport const ExperimentStatusEnum = defineEntityEnum({\n  name: 'ExperimentStatus',\n  values: ['DRAFT', 'RUNNING', 'PAUSED', 'COMPLETED', 'CANCELLED'] as const,\n  schema: 'lssm_feature_flags',\n  description: 'Status of an experiment.',\n});\n\n/**\n * FeatureFlag entity - defines a feature flag.\n */\nexport const FeatureFlagEntity = defineEntity({\n  name: 'FeatureFlag',\n  description: 'A feature flag for controlling feature availability.',\n  schema: 'lssm_feature_flags',\n  map: 'feature_flag',\n  fields: {\n    id: field.id({ description: 'Unique flag identifier' }),\n    key: field.string({\n      isUnique: true,\n      description: 'Flag key (e.g., new_dashboard)',\n    }),\n    name: field.string({ description: 'Human-readable name' }),\n    description: field.string({\n      isOptional: true,\n      description: 'Description of the flag',\n    }),\n\n    // Status and default value\n    status: field.enum('FlagStatus', {\n      default: 'OFF',\n      description: 'Flag status',\n    }),\n    defaultValue: field.boolean({\n      default: false,\n      description: 'Default value when no rules match',\n    }),\n\n    // Multivariate support\n    variants: field.json({\n      isOptional: true,\n      description: 'Variant definitions for multivariate flags',\n    }),\n\n    // Scope\n    orgId: field.string({\n      isOptional: true,\n      description: 'Organization scope (null = global)',\n    }),\n\n    // Metadata\n    tags: field.json({\n      isOptional: true,\n      description: 'Tags for categorization',\n    }),\n    metadata: field.json({\n      isOptional: true,\n      description: 'Additional metadata',\n    }),\n\n    // Timestamps\n    createdAt: field.createdAt(),\n    updatedAt: field.updatedAt(),\n\n    // Relations\n    targetingRules: field.hasMany('FlagTargetingRule'),\n    experiments: field.hasMany('Experiment'),\n    evaluations: field.hasMany('FlagEvaluation'),\n  },\n  indexes: [index.on(['orgId', 'key']), index.on(['status'])],\n  enums: [FlagStatusEnum],\n});\n\n/**\n * FlagTargetingRule entity - conditions for targeting.\n */\nexport const FlagTargetingRuleEntity = defineEntity({\n  name: 'FlagTargetingRule',\n  description: 'A targeting rule for conditional flag evaluation.',\n  schema: 'lssm_feature_flags',\n  map: 'flag_targeting_rule',\n  fields: {\n    id: field.id({ description: 'Unique rule identifier' }),\n    flagId: field.foreignKey({ description: 'Parent feature flag' }),\n\n    // Rule definition\n    name: field.string({\n      isOptional: true,\n      description: 'Rule name for debugging',\n    }),\n    priority: field.int({\n      default: 0,\n      description: 'Rule priority (lower = higher priority)',\n    }),\n    enabled: field.boolean({\n      default: true,\n      description: 'Whether rule is active',\n    }),\n\n    // Condition\n    attribute: field.string({\n      description: 'Target attribute (userId, orgId, plan, segment, etc.)',\n    }),\n    operator: field.enum('RuleOperator', {\n      description: 'Comparison operator',\n    }),\n    value: field.json({ description: 'Target value(s)' }),\n\n    // Result\n    rolloutPercentage: field.int({\n      isOptional: true,\n      description: 'Percentage for gradual rollout (0-100)',\n    }),\n    serveValue: field.boolean({\n      isOptional: true,\n      description: 'Boolean value to serve',\n    }),\n    serveVariant: field.string({\n      isOptional: true,\n      description: 'Variant key to serve (for multivariate)',\n    }),\n\n    // Timestamps\n    createdAt: field.createdAt(),\n    updatedAt: field.updatedAt(),\n\n    // Relations\n    flag: field.belongsTo('FeatureFlag', ['flagId'], ['id'], {\n      onDelete: 'Cascade',\n    }),\n  },\n  indexes: [index.on(['flagId', 'priority']), index.on(['attribute'])],\n  enums: [RuleOperatorEnum],\n});\n\n/**\n * Experiment entity - A/B test configuration.\n */\nexport const ExperimentEntity = defineEntity({\n  name: 'Experiment',\n  description: 'An A/B test experiment.',\n  schema: 'lssm_feature_flags',\n  map: 'experiment',\n  fields: {\n    id: field.id({ description: 'Unique experiment identifier' }),\n    key: field.string({ isUnique: true, description: 'Experiment key' }),\n    name: field.string({ description: 'Human-readable name' }),\n    description: field.string({\n      isOptional: true,\n      description: 'Experiment description',\n    }),\n    hypothesis: field.string({\n      isOptional: true,\n      description: 'Experiment hypothesis',\n    }),\n\n    // Associated flag\n    flagId: field.foreignKey({ description: 'Associated feature flag' }),\n\n    // Configuration\n    status: field.enum('ExperimentStatus', {\n      default: 'DRAFT',\n      description: 'Experiment status',\n    }),\n    variants: field.json({\n      description: 'Variant definitions with split ratios',\n    }),\n    metrics: field.json({ isOptional: true, description: 'Metrics to track' }),\n\n    // Targeting\n    audiencePercentage: field.int({\n      default: 100,\n      description: 'Percentage of audience to include',\n    }),\n    audienceFilter: field.json({\n      isOptional: true,\n      description: 'Audience filter criteria',\n    }),\n\n    // Timeline\n    scheduledStartAt: field.dateTime({\n      isOptional: true,\n      description: 'Scheduled start time',\n    }),\n    scheduledEndAt: field.dateTime({\n      isOptional: true,\n      description: 'Scheduled end time',\n    }),\n    startedAt: field.dateTime({\n      isOptional: true,\n      description: 'Actual start time',\n    }),\n    endedAt: field.dateTime({\n      isOptional: true,\n      description: 'Actual end time',\n    }),\n\n    // Results\n    winningVariant: field.string({\n      isOptional: true,\n      description: 'Declared winning variant',\n    }),\n    results: field.json({\n      isOptional: true,\n      description: 'Experiment results summary',\n    }),\n\n    // Scope\n    orgId: field.string({\n      isOptional: true,\n      description: 'Organization scope',\n    }),\n\n    // Timestamps\n    createdAt: field.createdAt(),\n    updatedAt: field.updatedAt(),\n\n    // Relations\n    flag: field.belongsTo('FeatureFlag', ['flagId'], ['id'], {\n      onDelete: 'Cascade',\n    }),\n    assignments: field.hasMany('ExperimentAssignment'),\n  },\n  indexes: [\n    index.on(['status']),\n    index.on(['orgId', 'status']),\n    index.on(['flagId']),\n  ],\n  enums: [ExperimentStatusEnum],\n});\n\n/**\n * ExperimentAssignment entity - tracks which variant a subject is assigned to.\n */\nexport const ExperimentAssignmentEntity = defineEntity({\n  name: 'ExperimentAssignment',\n  description: 'Tracks experiment variant assignments.',\n  schema: 'lssm_feature_flags',\n  map: 'experiment_assignment',\n  fields: {\n    id: field.id({ description: 'Unique assignment identifier' }),\n    experimentId: field.foreignKey({ description: 'Parent experiment' }),\n\n    // Subject\n    subjectType: field.string({\n      description: 'Subject type (user, org, session)',\n    }),\n    subjectId: field.string({ description: 'Subject identifier' }),\n\n    // Assignment\n    variant: field.string({ description: 'Assigned variant key' }),\n    bucket: field.int({ description: 'Hash bucket (0-99)' }),\n\n    // Context\n    context: field.json({\n      isOptional: true,\n      description: 'Context at assignment time',\n    }),\n\n    // Timestamps\n    assignedAt: field.dateTime({ description: 'Assignment timestamp' }),\n\n    // Relations\n    experiment: field.belongsTo('Experiment', ['experimentId'], ['id'], {\n      onDelete: 'Cascade',\n    }),\n  },\n  indexes: [\n    index.unique(['experimentId', 'subjectType', 'subjectId'], {\n      name: 'experiment_assignment_unique',\n    }),\n    index.on(['subjectType', 'subjectId']),\n  ],\n});\n\n/**\n * FlagEvaluation entity - evaluation log for analytics.\n */\nexport const FlagEvaluationEntity = defineEntity({\n  name: 'FlagEvaluation',\n  description: 'Log of flag evaluations for debugging and analytics.',\n  schema: 'lssm_feature_flags',\n  map: 'flag_evaluation',\n  fields: {\n    id: field.id({ description: 'Unique evaluation identifier' }),\n    flagId: field.foreignKey({ description: 'Evaluated flag' }),\n    flagKey: field.string({\n      description: 'Flag key (denormalized for queries)',\n    }),\n\n    // Subject\n    subjectType: field.string({\n      description: 'Subject type (user, org, anonymous)',\n    }),\n    subjectId: field.string({ description: 'Subject identifier' }),\n\n    // Result\n    result: field.boolean({ description: 'Evaluation result' }),\n    variant: field.string({\n      isOptional: true,\n      description: 'Served variant (for multivariate)',\n    }),\n\n    // Match info\n    matchedRuleId: field.string({\n      isOptional: true,\n      description: 'Rule that matched (if any)',\n    }),\n    reason: field.string({\n      description: 'Evaluation reason (default, rule, experiment, etc.)',\n    }),\n\n    // Context\n    context: field.json({\n      isOptional: true,\n      description: 'Evaluation context',\n    }),\n\n    // Timestamps\n    evaluatedAt: field.dateTime({ description: 'Evaluation timestamp' }),\n\n    // Relations\n    flag: field.belongsTo('FeatureFlag', ['flagId'], ['id'], {\n      onDelete: 'Cascade',\n    }),\n  },\n  indexes: [\n    index.on(['flagKey', 'evaluatedAt']),\n    index.on(['subjectType', 'subjectId', 'evaluatedAt']),\n    index.on(['flagId', 'evaluatedAt']),\n  ],\n});\n\n/**\n * All feature flag entities for schema composition.\n */\nexport const featureFlagEntities = [\n  FeatureFlagEntity,\n  FlagTargetingRuleEntity,\n  ExperimentEntity,\n  ExperimentAssignmentEntity,\n  FlagEvaluationEntity,\n];\n\n/**\n * Module schema contribution for feature flags.\n */\nexport const featureFlagsSchemaContribution: ModuleSchemaContribution = {\n  moduleId: '@contractspec/lib.feature-flags',\n  entities: featureFlagEntities,\n  enums: [FlagStatusEnum, RuleOperatorEnum, ExperimentStatusEnum],\n};\n"],"mappings":"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"}

package/dist/evaluation/index.d.ts

@@ -0,0 +1,163 @@
+//#region src/evaluation/index.d.ts
+/**
+ * Feature flag evaluation engine.
+ *
+ * Provides deterministic evaluation of feature flags based on targeting rules
+ * and experiment assignments.
+ */
+interface EvaluationContext {
+  /** User identifier */
+  userId?: string;
+  /** Organization identifier */
+  orgId?: string;
+  /** User's plan (free, pro, enterprise, etc.) */
+  plan?: string;
+  /** User segment or cohort */
+  segment?: string;
+  /** Session identifier for anonymous users */
+  sessionId?: string;
+  /** Additional custom attributes */
+  attributes?: Record<string, unknown>;
+}
+interface FeatureFlag {
+  id: string;
+  key: string;
+  status: 'OFF' | 'ON' | 'GRADUAL';
+  defaultValue: boolean;
+  variants?: VariantConfig[];
+}
+interface TargetingRule {
+  id: string;
+  priority: number;
+  enabled: boolean;
+  attribute: string;
+  operator: RuleOperator;
+  value: unknown;
+  rolloutPercentage?: number;
+  serveValue?: boolean;
+  serveVariant?: string;
+}
+interface Experiment {
+  id: string;
+  key: string;
+  status: 'DRAFT' | 'RUNNING' | 'PAUSED' | 'COMPLETED' | 'CANCELLED';
+  variants: ExperimentVariant[];
+  audiencePercentage: number;
+  audienceFilter?: Record<string, unknown>;
+}
+interface VariantConfig {
+  key: string;
+  name: string;
+  description?: string;
+  weight?: number;
+}
+interface ExperimentVariant {
+  key: string;
+  name: string;
+  percentage: number;
+}
+interface EvaluationResult {
+  enabled: boolean;
+  variant?: string;
+  reason: EvaluationReason;
+  ruleId?: string;
+  experimentId?: string;
+}
+type EvaluationReason = 'FLAG_OFF' | 'FLAG_ON' | 'DEFAULT_VALUE' | 'RULE_MATCH' | 'PERCENTAGE_ROLLOUT' | 'EXPERIMENT_VARIANT' | 'FLAG_NOT_FOUND';
+type RuleOperator = 'EQ' | 'NEQ' | 'IN' | 'NIN' | 'CONTAINS' | 'NOT_CONTAINS' | 'GT' | 'GTE' | 'LT' | 'LTE' | 'PERCENTAGE';
+/**
+ * Simple hash function for consistent bucketing.
+ * Uses a deterministic algorithm so the same input always produces the same bucket.
+ */
+declare function hashToBucket(value: string, seed?: string): number;
+/**
+ * Get subject identifier from context for consistent hashing.
+ */
+declare function getSubjectId(context: EvaluationContext): string;
+/**
+ * Evaluate a single targeting rule condition.
+ */
+declare function evaluateRuleCondition(rule: TargetingRule, context: EvaluationContext): boolean;
+interface FlagRepository {
+  getFlag(key: string, orgId?: string): Promise<FeatureFlag | null>;
+  getRules(flagId: string): Promise<TargetingRule[]>;
+  getActiveExperiment(flagId: string): Promise<Experiment | null>;
+  getExperimentAssignment(experimentId: string, subjectType: string, subjectId: string): Promise<string | null>;
+  saveExperimentAssignment(experimentId: string, subjectType: string, subjectId: string, variant: string, bucket: number): Promise<void>;
+}
+interface EvaluationLogger {
+  log(evaluation: {
+    flagId: string;
+    flagKey: string;
+    subjectType: string;
+    subjectId: string;
+    result: boolean;
+    variant?: string;
+    reason: string;
+    ruleId?: string;
+    experimentId?: string;
+    context?: EvaluationContext;
+  }): void;
+}
+interface FlagEvaluatorOptions {
+  repository: FlagRepository;
+  logger?: EvaluationLogger;
+  /** Whether to log evaluations (default: false for performance) */
+  logEvaluations?: boolean;
+}
+/**
+ * Feature flag evaluator.
+ *
+ * Evaluates flags based on:
+ * 1. Flag status (OFF/ON/GRADUAL)
+ * 2. Targeting rules (in priority order)
+ * 3. Experiments (if running)
+ * 4. Default value (fallback)
+ */
+declare class FlagEvaluator {
+  private repository;
+  private logger?;
+  private logEvaluations;
+  constructor(options: FlagEvaluatorOptions);
+  /**
+   * Evaluate a feature flag.
+   */
+  evaluate(key: string, context: EvaluationContext): Promise<EvaluationResult>;
+  /**
+   * Evaluate experiment and assign variant.
+   */
+  private evaluateExperiment;
+  /**
+   * Assign a variant based on bucket and variant percentages.
+   */
+  private assignVariant;
+  /**
+   * Create evaluation result.
+   */
+  private makeResult;
+  /**
+   * Log evaluation and return result.
+   */
+  private logAndReturn;
+}
+/**
+ * In-memory flag repository for testing and development.
+ */
+declare class InMemoryFlagRepository implements FlagRepository {
+  private flags;
+  private rules;
+  private experiments;
+  private assignments;
+  addFlag(flag: FeatureFlag): void;
+  addRule(flagId: string, rule: TargetingRule): void;
+  addExperiment(experiment: Experiment, flagId: string): void;
+  getFlag(key: string): Promise<FeatureFlag | null>;
+  getRules(flagId: string): Promise<TargetingRule[]>;
+  getActiveExperiment(flagId: string): Promise<Experiment | null>;
+  getExperimentAssignment(experimentId: string, subjectType: string, subjectId: string): Promise<string | null>;
+  saveExperimentAssignment(experimentId: string, subjectType: string, subjectId: string, variant: string): Promise<void>;
+  clear(): void;
+}
+//#endregion
+export { EvaluationContext, EvaluationLogger, EvaluationReason, EvaluationResult, Experiment, ExperimentVariant, FeatureFlag, FlagEvaluator, FlagEvaluatorOptions, FlagRepository, InMemoryFlagRepository, RuleOperator, TargetingRule, VariantConfig, evaluateRuleCondition, getSubjectId, hashToBucket };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/evaluation/index.ts"],"sourcesContent":[],"mappings":";;AASA;AAeA;AAQA;AAYA;AASA;AAOiB,UAnDA,iBAAA,CAmDiB;EAMjB;EAQL,MAAA,CAAA,EAAA,MAAA;EASA;EAmBI,KAAA,CAAA,EAAA,MAAA;EAeA;EASA,IAAA,CAAA,EAAA,MAAA;EAwFC;EAC+B,OAAA,CAAA,EAAA,MAAA;EAAR;EACJ,SAAA,CAAA,EAAA,MAAA;EAAR;EACmB,UAAA,CAAA,EApMhC,MAoMgC,CAAA,MAAA,EAAA,OAAA,CAAA;;AAK1C,UAtMY,WAAA,CAsMZ;EAOA,EAAA,EAAA,MAAA;EAAO,GAAA,EAAA,MAAA;EAGK,MAAA,EAAA,KAAA,GAAA,IAAgB,GAAA,SAWnB;EAIG,YAAA,EAAA,OAAA;EAgBJ,QAAA,CAAA,EA1OA,aA0Oa,EAAA;;AAgBb,UAvPI,aAAA,CAuPJ;EACA,EAAA,EAAA,MAAA;EAAR,QAAA,EAAA,MAAA;EAAO,OAAA,EAAA,OAAA;EAsMC,SAAA,EAAA,MAAA;EAMG,QAAA,EA/bJ,YA+bI;EAIgB,KAAA,EAAA,OAAA;EAMJ,iBAAA,CAAA,EAAA,MAAA;EAIU,UAAA,CAAA,EAAA,OAAA;EAAR,YAAA,CAAA,EAAA,MAAA;;AAII,UA1cjB,UAAA,CA0ciB;EAImB,EAAA,EAAA,MAAA;EAAR,GAAA,EAAA,MAAA;EAQxC,MAAA,EAAA,OAAA,GAAA,SAAA,GAAA,QAAA,GAAA,WAAA,GAAA,WAAA;EAUA,QAAA,EA5dO,iBA4dP,EAAA;EA9C0C,kBAAA,EAAA,MAAA;EAAc,cAAA,CAAA,EA5a1C,MA4a0C,CAAA,MAAA,EAAA,OAAA,CAAA;;UAza5C,aAAA;;;;;;UAOA,iBAAA;;;;;UAMA,gBAAA;;;UAGP;;;;KAKE,gBAAA;KASA,YAAA;;;;;iBAmBI,YAAA;;;;iBAeA,YAAA,UAAsB;;;;iBAStB,qBAAA,OACR,wBACG;UAsFM,cAAA;wCACuB,QAAQ;4BACpB,QAAQ;uCACG,QAAQ;yFAK1C;2HAOA;;UAGY,gBAAA;;;;;;;;;;;cAWH;;;UAIG,oBAAA;cACH;WACH;;;;;;;;;;;;;cAcE,aAAA;;;;uBAKU;;;;iCAWV,oBACR,QAAQ;;;;;;;;;;;;;;;;;;;;;cAsMA,sBAAA,YAAkC;;;;;gBAM/B;gCAIgB;4BAMJ;wBAIE,QAAQ;4BAIJ,QAAQ;uCAIG,QAAQ;yFAQhD;2GAUA"}