@contractspec/lib.feature-flags 1.57.0 → 1.58.0

package/dist/browser/index.js

@@ -0,0 +1,1583 @@
+// src/contracts/index.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var OWNERS = ["platform.feature-flags"];
+var FeatureFlagModel = defineSchemaModel({
+  name: "FeatureFlag",
+  description: "Represents a feature flag",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    defaultValue: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    variants: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    tags: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var TargetingRuleModel = defineSchemaModel({
+  name: "TargetingRule",
+  description: "Represents a targeting rule",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    enabled: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    attribute: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    operator: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    value: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    rolloutPercentage: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    serveValue: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    serveVariant: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var ExperimentModel = defineSchemaModel({
+  name: "Experiment",
+  description: "Represents an experiment",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    hypothesis: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    variants: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    metrics: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    audiencePercentage: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false
+    },
+    startedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    endedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    winningVariant: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    results: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var EvaluationResultModel = defineSchemaModel({
+  name: "EvaluationResult",
+  description: "Result of flag evaluation",
+  fields: {
+    enabled: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    variant: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ruleId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    experimentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var CreateFlagInput = defineSchemaModel({
+  name: "CreateFlagInput",
+  description: "Input for creating a feature flag",
+  fields: {
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    defaultValue: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    variants: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    tags: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+var UpdateFlagInput = defineSchemaModel({
+  name: "UpdateFlagInput",
+  description: "Input for updating a feature flag",
+  fields: {
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    defaultValue: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    variants: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    tags: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+var DeleteFlagInput = defineSchemaModel({
+  name: "DeleteFlagInput",
+  description: "Input for deleting a feature flag",
+  fields: {
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var ToggleFlagInput = defineSchemaModel({
+  name: "ToggleFlagInput",
+  description: "Input for toggling a feature flag",
+  fields: {
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var GetFlagInput = defineSchemaModel({
+  name: "GetFlagInput",
+  description: "Input for getting a feature flag",
+  fields: {
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var ListFlagsInput = defineSchemaModel({
+  name: "ListFlagsInput",
+  description: "Input for listing feature flags",
+  fields: {
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    tags: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    offset: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var ListFlagsOutput = defineSchemaModel({
+  name: "ListFlagsOutput",
+  description: "Output for listing feature flags",
+  fields: {
+    flags: { type: FeatureFlagModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var EvaluateFlagInput = defineSchemaModel({
+  name: "EvaluateFlagInput",
+  description: "Input for evaluating a feature flag",
+  fields: {
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    context: { type: ScalarTypeEnum.JSON(), isOptional: false }
+  }
+});
+var CreateRuleInput = defineSchemaModel({
+  name: "CreateRuleInput",
+  description: "Input for creating a targeting rule",
+  fields: {
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    priority: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    attribute: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    operator: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    value: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    rolloutPercentage: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    serveValue: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    serveVariant: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var DeleteRuleInput = defineSchemaModel({
+  name: "DeleteRuleInput",
+  description: "Input for deleting a targeting rule",
+  fields: {
+    ruleId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var CreateExperimentInput = defineSchemaModel({
+  name: "CreateExperimentInput",
+  description: "Input for creating an experiment",
+  fields: {
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    hypothesis: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    flagId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    variants: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    metrics: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    audiencePercentage: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    scheduledStartAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    scheduledEndAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var StartExperimentInput = defineSchemaModel({
+  name: "StartExperimentInput",
+  description: "Input for starting an experiment",
+  fields: {
+    experimentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var StopExperimentInput = defineSchemaModel({
+  name: "StopExperimentInput",
+  description: "Input for stopping an experiment",
+  fields: {
+    experimentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    winningVariant: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    }
+  }
+});
+var GetExperimentInput = defineSchemaModel({
+  name: "GetExperimentInput",
+  description: "Input for getting an experiment",
+  fields: {
+    experimentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var SuccessOutput = defineSchemaModel({
+  name: "SuccessOutput",
+  description: "Generic success output",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var CreateFlagContract = defineCommand({
+  meta: {
+    key: "flag.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "create"],
+    description: "Create a new feature flag.",
+    goal: "Define a new feature flag for toggling features.",
+    context: "Called when setting up a new feature flag."
+  },
+  io: {
+    input: CreateFlagInput,
+    output: FeatureFlagModel,
+    errors: {
+      KEY_ALREADY_EXISTS: {
+        description: "Flag key already exists",
+        http: 409,
+        gqlCode: "FLAG_KEY_EXISTS",
+        when: "A flag with this key already exists"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var UpdateFlagContract = defineCommand({
+  meta: {
+    key: "flag.update",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "update"],
+    description: "Update an existing feature flag.",
+    goal: "Modify flag configuration.",
+    context: "Called when adjusting flag settings."
+  },
+  io: {
+    input: UpdateFlagInput,
+    output: FeatureFlagModel,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var DeleteFlagContract = defineCommand({
+  meta: {
+    key: "flag.delete",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "delete"],
+    description: "Delete a feature flag.",
+    goal: "Remove a feature flag and all its rules.",
+    context: "Called when a flag is no longer needed."
+  },
+  io: {
+    input: DeleteFlagInput,
+    output: SuccessOutput,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag ID is invalid"
+      },
+      FLAG_HAS_ACTIVE_EXPERIMENT: {
+        description: "Flag has an active experiment",
+        http: 409,
+        gqlCode: "FLAG_HAS_ACTIVE_EXPERIMENT",
+        when: "Cannot delete flag with running experiment"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var ToggleFlagContract = defineCommand({
+  meta: {
+    key: "flag.toggle",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "toggle"],
+    description: "Toggle a feature flag status.",
+    goal: "Quickly enable or disable a feature.",
+    context: "Called when turning a feature on or off."
+  },
+  io: {
+    input: ToggleFlagInput,
+    output: FeatureFlagModel,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag ID is invalid"
+      },
+      INVALID_STATUS: {
+        description: "Invalid status value",
+        http: 400,
+        gqlCode: "INVALID_STATUS",
+        when: "Status must be OFF, ON, or GRADUAL"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetFlagContract = defineQuery({
+  meta: {
+    key: "flag.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "get"],
+    description: "Get a feature flag by key.",
+    goal: "Retrieve flag configuration.",
+    context: "Called to inspect flag details."
+  },
+  io: {
+    input: GetFlagInput,
+    output: FeatureFlagModel,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag key is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var ListFlagsContract = defineQuery({
+  meta: {
+    key: "flag.list",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "list"],
+    description: "List all feature flags.",
+    goal: "View all configured flags.",
+    context: "Admin dashboard."
+  },
+  io: {
+    input: ListFlagsInput,
+    output: ListFlagsOutput
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var EvaluateFlagContract = defineQuery({
+  meta: {
+    key: "flag.evaluate",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "evaluate"],
+    description: "Evaluate a feature flag for a given context.",
+    goal: "Determine if a feature should be enabled.",
+    context: "Called at runtime to check feature availability."
+  },
+  io: {
+    input: EvaluateFlagInput,
+    output: EvaluationResultModel,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag key is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "anonymous"
+  }
+});
+var CreateRuleContract = defineCommand({
+  meta: {
+    key: "flag.rule.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "rule", "create"],
+    description: "Create a targeting rule for a flag.",
+    goal: "Add conditional targeting to a flag.",
+    context: "Called when setting up targeting."
+  },
+  io: {
+    input: CreateRuleInput,
+    output: TargetingRuleModel,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag ID is invalid"
+      },
+      INVALID_OPERATOR: {
+        description: "Invalid operator",
+        http: 400,
+        gqlCode: "INVALID_OPERATOR",
+        when: "Operator is not supported"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var DeleteRuleContract = defineCommand({
+  meta: {
+    key: "flag.rule.delete",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "rule", "delete"],
+    description: "Delete a targeting rule.",
+    goal: "Remove a targeting rule from a flag.",
+    context: "Called when removing targeting conditions."
+  },
+  io: {
+    input: DeleteRuleInput,
+    output: SuccessOutput,
+    errors: {
+      RULE_NOT_FOUND: {
+        description: "Rule does not exist",
+        http: 404,
+        gqlCode: "RULE_NOT_FOUND",
+        when: "Rule ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var CreateExperimentContract = defineCommand({
+  meta: {
+    key: "experiment.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "experiment", "create"],
+    description: "Create an A/B test experiment.",
+    goal: "Set up an experiment with variants.",
+    context: "Called when setting up A/B testing."
+  },
+  io: {
+    input: CreateExperimentInput,
+    output: ExperimentModel,
+    errors: {
+      FLAG_NOT_FOUND: {
+        description: "Flag does not exist",
+        http: 404,
+        gqlCode: "FLAG_NOT_FOUND",
+        when: "Flag ID is invalid"
+      },
+      EXPERIMENT_KEY_EXISTS: {
+        description: "Experiment key already exists",
+        http: 409,
+        gqlCode: "EXPERIMENT_KEY_EXISTS",
+        when: "An experiment with this key already exists"
+      },
+      INVALID_VARIANTS: {
+        description: "Invalid variant configuration",
+        http: 400,
+        gqlCode: "INVALID_VARIANTS",
+        when: "Variant percentages must sum to 100"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var StartExperimentContract = defineCommand({
+  meta: {
+    key: "experiment.start",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "experiment", "start"],
+    description: "Start an experiment.",
+    goal: "Begin collecting data for an experiment.",
+    context: "Called when ready to run an A/B test."
+  },
+  io: {
+    input: StartExperimentInput,
+    output: ExperimentModel,
+    errors: {
+      EXPERIMENT_NOT_FOUND: {
+        description: "Experiment does not exist",
+        http: 404,
+        gqlCode: "EXPERIMENT_NOT_FOUND",
+        when: "Experiment ID is invalid"
+      },
+      EXPERIMENT_ALREADY_RUNNING: {
+        description: "Experiment is already running",
+        http: 409,
+        gqlCode: "EXPERIMENT_ALREADY_RUNNING",
+        when: "Cannot start an experiment that is already running"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var StopExperimentContract = defineCommand({
+  meta: {
+    key: "experiment.stop",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "experiment", "stop"],
+    description: "Stop an experiment.",
+    goal: "End an experiment and optionally declare a winner.",
+    context: "Called when concluding an A/B test."
+  },
+  io: {
+    input: StopExperimentInput,
+    output: ExperimentModel,
+    errors: {
+      EXPERIMENT_NOT_FOUND: {
+        description: "Experiment does not exist",
+        http: 404,
+        gqlCode: "EXPERIMENT_NOT_FOUND",
+        when: "Experiment ID is invalid"
+      },
+      EXPERIMENT_NOT_RUNNING: {
+        description: "Experiment is not running",
+        http: 409,
+        gqlCode: "EXPERIMENT_NOT_RUNNING",
+        when: "Cannot stop an experiment that is not running"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetExperimentContract = defineQuery({
+  meta: {
+    key: "experiment.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["feature-flags", "experiment", "get"],
+    description: "Get experiment details.",
+    goal: "View experiment configuration and results.",
+    context: "Called to inspect experiment status."
+  },
+  io: {
+    input: GetExperimentInput,
+    output: ExperimentModel,
+    errors: {
+      EXPERIMENT_NOT_FOUND: {
+        description: "Experiment does not exist",
+        http: 404,
+        gqlCode: "EXPERIMENT_NOT_FOUND",
+        when: "Experiment ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+
+// src/docs/feature-flags.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var featureFlagsDocBlocks = [
+  {
+    id: "docs.feature-flags.overview",
+    title: "Feature Flags & Experiments",
+    summary: "Reusable, spec-first feature flag and experiment module with targeting, gradual rollout, multivariate variants, and evaluation logging.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/feature-flags/overview",
+    tags: ["feature-flags", "experiments", "progressive-delivery"],
+    body: `## What this module provides
+
+- **Entities**: FeatureFlag, FlagTargetingRule, Experiment, ExperimentAssignment, FlagEvaluation.
+- **Contracts**: create/update/delete/toggle/list/get flags; create/delete rules; evaluate flags; create/start/stop/get experiments.
+- **Events**: flag.created/updated/deleted/toggled, rule.created/deleted, experiment.created/started/stopped, flag.evaluated, experiment.variant_assigned.
+- **Evaluation Engine**: Deterministic evaluator with gradual rollout, rule priority, audience filters, and experiment bucketing.
+
+## How to use
+
+1) Compose schema
+ - Add \`featureFlagsSchemaContribution\` to your module composition.
+
+2) Register contracts/events
+ - Import exports from \`@contractspec/lib.feature-flags\` into your spec registry.
+
+3) Evaluate at runtime
+ - Instantiate \`FlagEvaluator\` with a repository implementation and optional logger.
+ - Evaluate with context attributes (userId, orgId, plan, segment, sessionId, attributes).
+
+4) Wire observability
+ - Emit audit trail on config changes; emit \`flag.evaluated\` for analytics.
+
+## Usage example
+
+${"```"}ts
+import {
+  FlagEvaluator,
+  InMemoryFlagRepository,
+} from '@contractspec/lib.feature-flags';
+
+const repo = new InMemoryFlagRepository();
+repo.addFlag({
+  id: 'flag-1',
+  key: 'new_dashboard',
+  status: 'GRADUAL',
+  defaultValue: false,
+});
+
+const evaluator = new FlagEvaluator({ repository: repo });
+const result = await evaluator.evaluate('new_dashboard', {
+  userId: 'user-123',
+  orgId: 'org-456',
+  plan: 'pro',
+});
+
+if (result.enabled) {
+  // serve the new dashboard
+}
+${"```"},
+
+## Guardrails
+
+- Keep flag keys stable and human-readable; avoid PII in context.
+- Ensure experiments’ variant percentages sum to 100; default flag status to OFF.
+- Use org-scoped flags for multi-tenant isolation.
+- Log evaluations only when needed to control volume; prefer sampling for noisy paths.
+`
+  }
+];
+registerDocBlocks(featureFlagsDocBlocks);
+// src/entities/index.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var FlagStatusEnum = defineEntityEnum({
+  name: "FlagStatus",
+  values: ["OFF", "ON", "GRADUAL"],
+  schema: "lssm_feature_flags",
+  description: "Status of a feature flag."
+});
+var 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."
+});
+var ExperimentStatusEnum = defineEntityEnum({
+  name: "ExperimentStatus",
+  values: ["DRAFT", "RUNNING", "PAUSED", "COMPLETED", "CANCELLED"],
+  schema: "lssm_feature_flags",
+  description: "Status of an experiment."
+});
+var 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]
+});
+var 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]
+});
+var 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]
+});
+var 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"])
+  ]
+});
+var 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"])
+  ]
+});
+var featureFlagEntities = [
+  FeatureFlagEntity,
+  FlagTargetingRuleEntity,
+  ExperimentEntity,
+  ExperimentAssignmentEntity,
+  FlagEvaluationEntity
+];
+var featureFlagsSchemaContribution = {
+  moduleId: "@contractspec/lib.feature-flags",
+  entities: featureFlagEntities,
+  enums: [FlagStatusEnum, RuleOperatorEnum, ExperimentStatusEnum]
+};
+
+// src/evaluation/index.ts
+function hashToBucket(value, seed = "") {
+  const input = `${seed}:${value}`;
+  let hash = 0;
+  for (let i = 0;i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash % 100);
+}
+function getSubjectId(context) {
+  return context.userId || context.sessionId || context.orgId || "anonymous";
+}
+function evaluateRuleCondition(rule, context) {
+  const attributeValue = getAttributeValue(rule.attribute, context);
+  switch (rule.operator) {
+    case "EQ":
+      return attributeValue === rule.value;
+    case "NEQ":
+      return attributeValue !== rule.value;
+    case "IN":
+      if (!Array.isArray(rule.value))
+        return false;
+      return rule.value.includes(attributeValue);
+    case "NIN":
+      if (!Array.isArray(rule.value))
+        return true;
+      return !rule.value.includes(attributeValue);
+    case "CONTAINS":
+      if (typeof attributeValue !== "string" || typeof rule.value !== "string")
+        return false;
+      return attributeValue.includes(rule.value);
+    case "NOT_CONTAINS":
+      if (typeof attributeValue !== "string" || typeof rule.value !== "string")
+        return true;
+      return !attributeValue.includes(rule.value);
+    case "GT":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue > rule.value;
+    case "GTE":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue >= rule.value;
+    case "LT":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue < rule.value;
+    case "LTE":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue <= rule.value;
+    case "PERCENTAGE":
+      return hashToBucket(getSubjectId(context), rule.attribute) < (typeof rule.value === "number" ? rule.value : 0);
+    default:
+      return false;
+  }
+}
+function getAttributeValue(attribute, context) {
+  switch (attribute) {
+    case "userId":
+      return context.userId;
+    case "orgId":
+      return context.orgId;
+    case "plan":
+      return context.plan;
+    case "segment":
+      return context.segment;
+    case "sessionId":
+      return context.sessionId;
+    default:
+      return context.attributes?.[attribute];
+  }
+}
+
+class FlagEvaluator {
+  repository;
+  logger;
+  logEvaluations;
+  constructor(options) {
+    this.repository = options.repository;
+    this.logger = options.logger;
+    this.logEvaluations = options.logEvaluations ?? false;
+  }
+  async evaluate(key, context) {
+    const orgId = context.orgId;
+    const flag = await this.repository.getFlag(key, orgId);
+    if (!flag) {
+      return this.makeResult(false, "FLAG_NOT_FOUND");
+    }
+    if (flag.status === "OFF") {
+      return this.logAndReturn(flag, context, this.makeResult(false, "FLAG_OFF"));
+    }
+    if (flag.status === "ON") {
+      return this.logAndReturn(flag, context, this.makeResult(true, "FLAG_ON"));
+    }
+    const rules = await this.repository.getRules(flag.id);
+    const sortedRules = [...rules].filter((r) => r.enabled).sort((a, b) => a.priority - b.priority);
+    for (const rule of sortedRules) {
+      if (evaluateRuleCondition(rule, context)) {
+        if (rule.rolloutPercentage !== undefined && rule.rolloutPercentage !== null) {
+          const bucket = hashToBucket(getSubjectId(context), flag.key);
+          if (bucket >= rule.rolloutPercentage) {
+            continue;
+          }
+        }
+        const enabled = rule.serveValue ?? true;
+        return this.logAndReturn(flag, context, this.makeResult(enabled, "RULE_MATCH", rule.serveVariant, rule.id));
+      }
+    }
+    const experiment = await this.repository.getActiveExperiment(flag.id);
+    if (experiment && experiment.status === "RUNNING") {
+      const result = await this.evaluateExperiment(experiment, context);
+      if (result) {
+        return this.logAndReturn(flag, context, result);
+      }
+    }
+    return this.logAndReturn(flag, context, this.makeResult(flag.defaultValue, "DEFAULT_VALUE"));
+  }
+  async evaluateExperiment(experiment, context) {
+    const subjectId = getSubjectId(context);
+    const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
+    const audienceBucket = hashToBucket(subjectId, `${experiment.key}:audience`);
+    if (audienceBucket >= experiment.audiencePercentage) {
+      return null;
+    }
+    let variant = await this.repository.getExperimentAssignment(experiment.id, subjectType, subjectId);
+    if (!variant) {
+      const variantBucket = hashToBucket(subjectId, experiment.key);
+      variant = this.assignVariant(experiment.variants, variantBucket);
+      await this.repository.saveExperimentAssignment(experiment.id, subjectType, subjectId, variant, variantBucket);
+    }
+    const enabled = variant !== "control";
+    return this.makeResult(enabled, "EXPERIMENT_VARIANT", variant, undefined, experiment.id);
+  }
+  assignVariant(variants, bucket) {
+    let cumulative = 0;
+    for (const variant of variants) {
+      cumulative += variant.percentage;
+      if (bucket < cumulative) {
+        return variant.key;
+      }
+    }
+    return variants[variants.length - 1]?.key ?? "control";
+  }
+  makeResult(enabled, reason, variant, ruleId, experimentId) {
+    return {
+      enabled,
+      variant,
+      reason,
+      ruleId,
+      experimentId
+    };
+  }
+  logAndReturn(flag, context, result) {
+    if (this.logEvaluations && this.logger) {
+      const subjectId = getSubjectId(context);
+      const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
+      this.logger.log({
+        flagId: flag.id,
+        flagKey: flag.key,
+        subjectType,
+        subjectId,
+        result: result.enabled,
+        variant: result.variant,
+        reason: result.reason,
+        ruleId: result.ruleId,
+        experimentId: result.experimentId,
+        context
+      });
+    }
+    return result;
+  }
+}
+
+class InMemoryFlagRepository {
+  flags = new Map;
+  rules = new Map;
+  experiments = new Map;
+  assignments = new Map;
+  addFlag(flag) {
+    this.flags.set(flag.key, flag);
+  }
+  addRule(flagId, rule) {
+    const existing = this.rules.get(flagId) || [];
+    existing.push(rule);
+    this.rules.set(flagId, existing);
+  }
+  addExperiment(experiment, flagId) {
+    this.experiments.set(flagId, experiment);
+  }
+  async getFlag(key) {
+    return this.flags.get(key) || null;
+  }
+  async getRules(flagId) {
+    return this.rules.get(flagId) || [];
+  }
+  async getActiveExperiment(flagId) {
+    return this.experiments.get(flagId) || null;
+  }
+  async getExperimentAssignment(experimentId, subjectType, subjectId) {
+    const key = `${experimentId}:${subjectType}:${subjectId}`;
+    return this.assignments.get(key) || null;
+  }
+  async saveExperimentAssignment(experimentId, subjectType, subjectId, variant) {
+    const key = `${experimentId}:${subjectType}:${subjectId}`;
+    this.assignments.set(key, variant);
+  }
+  clear() {
+    this.flags.clear();
+    this.rules.clear();
+    this.experiments.clear();
+    this.assignments.clear();
+  }
+}
+
+// src/events.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
+import { defineEvent } from "@contractspec/lib.contracts";
+var FlagCreatedPayload = defineSchemaModel2({
+  name: "FlagCreatedEventPayload",
+  description: "Payload when a feature flag is created",
+  fields: {
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    orgId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    createdBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var FlagUpdatedPayload = defineSchemaModel2({
+  name: "FlagUpdatedEventPayload",
+  description: "Payload when a feature flag is updated",
+  fields: {
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    changes: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+    updatedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    updatedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var FlagDeletedPayload = defineSchemaModel2({
+  name: "FlagDeletedEventPayload",
+  description: "Payload when a feature flag is deleted",
+  fields: {
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    deletedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    deletedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var FlagToggledPayload = defineSchemaModel2({
+  name: "FlagToggledEventPayload",
+  description: "Payload when a feature flag status is toggled",
+  fields: {
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    previousStatus: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    newStatus: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    toggledBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    toggledAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var RuleCreatedPayload = defineSchemaModel2({
+  name: "RuleCreatedEventPayload",
+  description: "Payload when a targeting rule is created",
+  fields: {
+    ruleId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    attribute: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    operator: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var RuleDeletedPayload = defineSchemaModel2({
+  name: "RuleDeletedEventPayload",
+  description: "Payload when a targeting rule is deleted",
+  fields: {
+    ruleId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    deletedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ExperimentCreatedPayload = defineSchemaModel2({
+  name: "ExperimentCreatedEventPayload",
+  description: "Payload when an experiment is created",
+  fields: {
+    experimentId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    variants: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+    createdBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ExperimentStartedPayload = defineSchemaModel2({
+  name: "ExperimentStartedEventPayload",
+  description: "Payload when an experiment starts",
+  fields: {
+    experimentId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    variants: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+    audiencePercentage: {
+      type: ScalarTypeEnum2.Int_unsecure(),
+      isOptional: false
+    },
+    startedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    startedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ExperimentStoppedPayload = defineSchemaModel2({
+  name: "ExperimentStoppedEventPayload",
+  description: "Payload when an experiment stops",
+  fields: {
+    experimentId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    reason: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    winningVariant: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    stoppedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    stoppedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var FlagEvaluatedPayload = defineSchemaModel2({
+  name: "FlagEvaluatedEventPayload",
+  description: "Payload when a flag is evaluated (for analytics)",
+  fields: {
+    flagId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    flagKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    result: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    variant: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    reason: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    evaluatedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var VariantAssignedPayload = defineSchemaModel2({
+  name: "VariantAssignedEventPayload",
+  description: "Payload when a subject is assigned to an experiment variant",
+  fields: {
+    experimentId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    experimentKey: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    variant: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    bucket: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    assignedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var FlagCreatedEvent = defineEvent({
+  meta: {
+    key: "flag.created",
+    version: "1.0.0",
+    description: "A feature flag has been created.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "create"]
+  },
+  payload: FlagCreatedPayload
+});
+var FlagUpdatedEvent = defineEvent({
+  meta: {
+    key: "flag.updated",
+    version: "1.0.0",
+    description: "A feature flag has been updated.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "update"]
+  },
+  payload: FlagUpdatedPayload
+});
+var FlagDeletedEvent = defineEvent({
+  meta: {
+    key: "flag.deleted",
+    version: "1.0.0",
+    description: "A feature flag has been deleted.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "delete"]
+  },
+  payload: FlagDeletedPayload
+});
+var FlagToggledEvent = defineEvent({
+  meta: {
+    key: "flag.toggled",
+    version: "1.0.0",
+    description: "A feature flag status has been toggled.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "toggle"]
+  },
+  payload: FlagToggledPayload
+});
+var RuleCreatedEvent = defineEvent({
+  meta: {
+    key: "flag.rule_created",
+    version: "1.0.0",
+    description: "A targeting rule has been created.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "rule", "create"]
+  },
+  payload: RuleCreatedPayload
+});
+var RuleDeletedEvent = defineEvent({
+  meta: {
+    key: "flag.rule_deleted",
+    version: "1.0.0",
+    description: "A targeting rule has been deleted.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "rule", "delete"]
+  },
+  payload: RuleDeletedPayload
+});
+var ExperimentCreatedEvent = defineEvent({
+  meta: {
+    key: "experiment.created",
+    version: "1.0.0",
+    description: "An experiment has been created.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "experiment", "create"]
+  },
+  payload: ExperimentCreatedPayload
+});
+var ExperimentStartedEvent = defineEvent({
+  meta: {
+    key: "experiment.started",
+    version: "1.0.0",
+    description: "An experiment has started.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "experiment", "start"]
+  },
+  payload: ExperimentStartedPayload
+});
+var ExperimentStoppedEvent = defineEvent({
+  meta: {
+    key: "experiment.stopped",
+    version: "1.0.0",
+    description: "An experiment has stopped.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "experiment", "stop"]
+  },
+  payload: ExperimentStoppedPayload
+});
+var FlagEvaluatedEvent = defineEvent({
+  meta: {
+    key: "flag.evaluated",
+    version: "1.0.0",
+    description: "A feature flag has been evaluated.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "evaluate"]
+  },
+  payload: FlagEvaluatedPayload
+});
+var VariantAssignedEvent = defineEvent({
+  meta: {
+    key: "experiment.variant_assigned",
+    version: "1.0.0",
+    description: "A subject has been assigned to an experiment variant.",
+    stability: "stable",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "experiment", "variant"]
+  },
+  payload: VariantAssignedPayload
+});
+var FeatureFlagEvents = {
+  FlagCreatedEvent,
+  FlagUpdatedEvent,
+  FlagDeletedEvent,
+  FlagToggledEvent,
+  RuleCreatedEvent,
+  RuleDeletedEvent,
+  ExperimentCreatedEvent,
+  ExperimentStartedEvent,
+  ExperimentStoppedEvent,
+  FlagEvaluatedEvent,
+  VariantAssignedEvent
+};
+
+// src/feature-flags.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var FeatureFlagsFeature = defineFeature({
+  meta: {
+    key: "feature-flags",
+    version: "1.0.0",
+    title: "Feature Flags",
+    description: "Feature flag management with targeting rules and A/B experiments",
+    domain: "platform",
+    owners: ["@platform.feature-flags"],
+    tags: ["feature-flags", "experiments", "targeting"],
+    stability: "stable"
+  },
+  operations: [
+    { key: "flag.create", version: "1.0.0" },
+    { key: "flag.update", version: "1.0.0" },
+    { key: "flag.delete", version: "1.0.0" },
+    { key: "flag.toggle", version: "1.0.0" },
+    { key: "flag.get", version: "1.0.0" },
+    { key: "flag.list", version: "1.0.0" },
+    { key: "flag.evaluate", version: "1.0.0" },
+    { key: "flag.rule.create", version: "1.0.0" },
+    { key: "flag.rule.delete", version: "1.0.0" },
+    { key: "experiment.create", version: "1.0.0" },
+    { key: "experiment.start", version: "1.0.0" },
+    { key: "experiment.stop", version: "1.0.0" },
+    { key: "experiment.get", version: "1.0.0" }
+  ],
+  events: [
+    { key: "flag.created", version: "1.0.0" },
+    { key: "flag.updated", version: "1.0.0" },
+    { key: "flag.deleted", version: "1.0.0" },
+    { key: "flag.toggled", version: "1.0.0" },
+    { key: "flag.evaluated", version: "1.0.0" },
+    { key: "flag.rule_created", version: "1.0.0" },
+    { key: "flag.rule_deleted", version: "1.0.0" },
+    { key: "experiment.created", version: "1.0.0" },
+    { key: "experiment.started", version: "1.0.0" },
+    { key: "experiment.stopped", version: "1.0.0" },
+    { key: "experiment.variant_assigned", version: "1.0.0" }
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    provides: [
+      { key: "feature-flag", version: "1.0.0" },
+      { key: "experiments", version: "1.0.0" }
+    ],
+    requires: [{ key: "identity", version: "1.0.0" }]
+  }
+});
+export {
+  hashToBucket,
+  getSubjectId,
+  featureFlagsSchemaContribution,
+  featureFlagEntities,
+  evaluateRuleCondition,
+  VariantAssignedEvent,
+  UpdateFlagContract,
+  ToggleFlagContract,
+  TargetingRuleModel,
+  StopExperimentContract,
+  StartExperimentContract,
+  RuleOperatorEnum,
+  RuleDeletedEvent,
+  RuleCreatedEvent,
+  ListFlagsContract,
+  InMemoryFlagRepository,
+  GetFlagContract,
+  GetExperimentContract,
+  FlagUpdatedEvent,
+  FlagToggledEvent,
+  FlagTargetingRuleEntity,
+  FlagStatusEnum,
+  FlagEvaluator,
+  FlagEvaluationEntity,
+  FlagEvaluatedEvent,
+  FlagDeletedEvent,
+  FlagCreatedEvent,
+  FeatureFlagsFeature,
+  FeatureFlagModel,
+  FeatureFlagEvents,
+  FeatureFlagEntity,
+  ExperimentStoppedEvent,
+  ExperimentStatusEnum,
+  ExperimentStartedEvent,
+  ExperimentModel,
+  ExperimentEntity,
+  ExperimentCreatedEvent,
+  ExperimentAssignmentEntity,
+  EvaluationResultModel,
+  EvaluateFlagContract,
+  DeleteRuleContract,
+  DeleteFlagContract,
+  CreateRuleContract,
+  CreateFlagContract,
+  CreateExperimentContract
+};