@contractspec/lib.feature-flags 1.57.0 → 1.59.0

package/dist/browser/contracts/index.js

@@ -0,0 +1,636 @@
+// 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"
+  }
+});
+export {
+  UpdateFlagContract,
+  ToggleFlagContract,
+  TargetingRuleModel,
+  StopExperimentContract,
+  StartExperimentContract,
+  ListFlagsContract,
+  GetFlagContract,
+  GetExperimentContract,
+  FeatureFlagModel,
+  ExperimentModel,
+  EvaluationResultModel,
+  EvaluateFlagContract,
+  DeleteRuleContract,
+  DeleteFlagContract,
+  CreateRuleContract,
+  CreateFlagContract,
+  CreateExperimentContract
+};

package/dist/browser/docs/feature-flags.docblock.js

@@ -0,0 +1,71 @@
+// 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);