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

package/dist/contracts/src/server/rest-express.d.ts

@@ -0,0 +1,3 @@
+import "../operations/registry.js";
+import "../types.js";
+import "./rest-generic.js";

package/dist/contracts/src/server/rest-generic.d.ts

@@ -0,0 +1,2 @@
+import "../operations/registry.js";
+import "../types.js";

package/dist/contracts/src/server/rest-next-app.d.ts

@@ -0,0 +1,3 @@
+import "../operations/registry.js";
+import "../types.js";
+import "./rest-generic.js";

package/dist/contracts/src/server/rest-next-pages.d.ts

@@ -0,0 +1,3 @@
+import "../operations/registry.js";
+import "../types.js";
+import "./rest-generic.js";

package/dist/contracts/src/telemetry/anomaly.d.ts

@@ -0,0 +1,2 @@
+import "./spec.js";
+import "./tracker.js";

package/dist/contracts/src/telemetry/index.d.ts

@@ -0,0 +1,3 @@
+import "./spec.js";
+import "./anomaly.js";
+import "./tracker.js";

package/dist/contracts/src/telemetry/spec.d.ts

@@ -0,0 +1,2 @@
+import "../ownership.js";
+import "../registry.js";

package/dist/contracts/src/telemetry/tracker.d.ts

@@ -0,0 +1,2 @@
+import "./spec.js";
+import "./anomaly.js";

package/dist/contracts/src/tests/index.d.ts

@@ -0,0 +1,2 @@
+import { TestSpecRef } from "./spec.js";
+import "./runner.js";

package/dist/contracts/src/tests/runner.d.ts

@@ -0,0 +1,3 @@
+import "./spec.js";
+import "../types.js";
+import "../index.js";

package/dist/contracts/src/tests/spec.d.ts

@@ -0,0 +1,11 @@
+import "../ownership.js";
+
+//#region ../contracts/src/tests/spec.d.ts
+
+interface TestSpecRef {
+  key: string;
+  version?: string;
+}
+//#endregion
+export { TestSpecRef };
+//# sourceMappingURL=spec.d.ts.map

package/dist/contracts/src/tests/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../../../../../contracts/src/tests/spec.ts"],"sourcesContent":[],"mappings":";;;;UAiFiB,WAAA"}

package/dist/contracts/src/themes.d.ts

@@ -0,0 +1,2 @@
+import "./ownership.js";
+import "./registry.js";

package/dist/contracts/src/types.d.ts

@@ -0,0 +1,5 @@
+import "./policy/spec.js";
+import "./telemetry/index.js";
+import "./app-config/runtime.js";
+import "./experiments/spec-resolver.js";
+import "./events.js";

package/dist/contracts/src/workflow/adapters/db-adapter.d.ts

@@ -0,0 +1 @@
+import "../state.js";

package/dist/contracts/src/workflow/adapters/file-adapter.d.ts

@@ -0,0 +1 @@
+import "../state.js";

package/dist/contracts/src/workflow/adapters/index.d.ts

@@ -0,0 +1,3 @@
+import "./memory-store.js";
+import "./db-adapter.js";
+import "./file-adapter.js";

package/dist/contracts/src/workflow/adapters/memory-store.d.ts

@@ -0,0 +1 @@
+import "../state.js";

package/dist/contracts/src/workflow/index.d.ts

@@ -0,0 +1,5 @@
+import "./spec.js";
+import "./validation.js";
+import "./state.js";
+import "./runner.js";
+import "./adapters/index.js";

package/dist/contracts/src/workflow/overview.docblock.d.ts

@@ -0,0 +1 @@
+import "../docs/index.js";

package/dist/contracts/src/workflow/runner.d.ts

@@ -0,0 +1,5 @@
+import "../features/index.js";
+import "./spec.js";
+import "../app-config/runtime.js";
+import "../types.js";
+import "./state.js";

package/dist/contracts/src/workflow/spec.d.ts

@@ -0,0 +1,5 @@
+import "../ownership.js";
+import "../capabilities/index.js";
+import "../experiments/spec.js";
+import "../features/index.js";
+import "../registry.js";

package/dist/contracts/src/workflow/state.d.ts

@@ -0,0 +1 @@
+import "./spec.js";

package/dist/contracts/src/workflow/validation.d.ts

@@ -0,0 +1,3 @@
+import "../operations/registry.js";
+import "./spec.js";
+import "../forms/index.js";

package/dist/contracts/src/workspace-config/contractsrc-schema.d.ts

@@ -0,0 +1 @@
+import "zod";

package/dist/contracts/src/workspace-config/index.d.ts

@@ -0,0 +1 @@
+import "./contractsrc-schema.js";

package/dist/contracts/src/workspace-config/workspace-config.docblock.d.ts

@@ -0,0 +1 @@
+import "../docs/index.js";

package/dist/docs/feature-flags.docblock.d.ts

@@ -0,0 +1 @@
+export { };

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

@@ -0,0 +1,76 @@
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+
+//#region src/docs/feature-flags.docblock.ts
+registerDocBlocks([{
+	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.
+`
+}]);
+
+//#endregion
+//# sourceMappingURL=feature-flags.docblock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags.docblock.js","names":[],"sources":["../../src/docs/feature-flags.docblock.ts"],"sourcesContent":["import type { DocBlock } from '@contractspec/lib.contracts/docs';\nimport { registerDocBlocks } from '@contractspec/lib.contracts/docs';\n\nconst featureFlagsDocBlocks: DocBlock[] = [\n  {\n    id: 'docs.feature-flags.overview',\n    title: 'Feature Flags & Experiments',\n    summary:\n      'Reusable, spec-first feature flag and experiment module with targeting, gradual rollout, multivariate variants, and evaluation logging.',\n    kind: 'reference',\n    visibility: 'public',\n    route: '/docs/feature-flags/overview',\n    tags: ['feature-flags', 'experiments', 'progressive-delivery'],\n    body: `## What this module provides\n\n- **Entities**: FeatureFlag, FlagTargetingRule, Experiment, ExperimentAssignment, FlagEvaluation.\n- **Contracts**: create/update/delete/toggle/list/get flags; create/delete rules; evaluate flags; create/start/stop/get experiments.\n- **Events**: flag.created/updated/deleted/toggled, rule.created/deleted, experiment.created/started/stopped, flag.evaluated, experiment.variant_assigned.\n- **Evaluation Engine**: Deterministic evaluator with gradual rollout, rule priority, audience filters, and experiment bucketing.\n\n## How to use\n\n1) Compose schema\n - Add \\`featureFlagsSchemaContribution\\` to your module composition.\n\n2) Register contracts/events\n - Import exports from \\`@contractspec/lib.feature-flags\\` into your spec registry.\n\n3) Evaluate at runtime\n - Instantiate \\`FlagEvaluator\\` with a repository implementation and optional logger.\n - Evaluate with context attributes (userId, orgId, plan, segment, sessionId, attributes).\n\n4) Wire observability\n - Emit audit trail on config changes; emit \\`flag.evaluated\\` for analytics.\n\n## Usage example\n\n${'```'}ts\nimport {\n  FlagEvaluator,\n  InMemoryFlagRepository,\n} from '@contractspec/lib.feature-flags';\n\nconst repo = new InMemoryFlagRepository();\nrepo.addFlag({\n  id: 'flag-1',\n  key: 'new_dashboard',\n  status: 'GRADUAL',\n  defaultValue: false,\n});\n\nconst evaluator = new FlagEvaluator({ repository: repo });\nconst result = await evaluator.evaluate('new_dashboard', {\n  userId: 'user-123',\n  orgId: 'org-456',\n  plan: 'pro',\n});\n\nif (result.enabled) {\n  // serve the new dashboard\n}\n${'```'},\n\n## Guardrails\n\n- Keep flag keys stable and human-readable; avoid PII in context.\n- Ensure experiments’ variant percentages sum to 100; default flag status to OFF.\n- Use org-scoped flags for multi-tenant isolation.\n- Log evaluations only when needed to control volume; prefer sampling for noisy paths.\n`,\n  },\n];\n\nregisterDocBlocks(featureFlagsDocBlocks);\n"],"mappings":";;;AAyEA,kBAtE0C,CACxC;CACE,IAAI;CACJ,OAAO;CACP,SACE;CACF,MAAM;CACN,YAAY;CACZ,OAAO;CACP,MAAM;EAAC;EAAiB;EAAe;EAAuB;CAC9D,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDP,CACF,CAEuC"}

package/dist/docs/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/docs/index.js

@@ -0,0 +1 @@
+import "./feature-flags.docblock.js";

package/dist/entities/index.d.ts

@@ -0,0 +1,201 @@
+import { EntityEnumDef, EntityEnumField, EntityRelationField, EntityScalarField, EntitySpec, ModuleSchemaContribution } from "../schema/src/entity/types.js";
+import "../schema/src/index.js";
+
+//#region src/entities/index.d.ts
+/**
+ * Feature flag status enum.
+ */
+declare const FlagStatusEnum: EntityEnumDef;
+/**
+ * Targeting rule operator enum.
+ */
+declare const RuleOperatorEnum: EntityEnumDef;
+/**
+ * Experiment status enum.
+ */
+declare const ExperimentStatusEnum: EntityEnumDef;
+/**
+ * FeatureFlag entity - defines a feature flag.
+ */
+declare const FeatureFlagEntity: EntitySpec<{
+  id: EntityScalarField;
+  key: EntityScalarField;
+  name: EntityScalarField;
+  description: EntityScalarField;
+  status: EntityEnumField;
+  defaultValue: EntityScalarField;
+  variants: EntityScalarField;
+  orgId: EntityScalarField;
+  tags: EntityScalarField;
+  metadata: EntityScalarField;
+  createdAt: EntityScalarField;
+  updatedAt: EntityScalarField;
+  targetingRules: EntityRelationField;
+  experiments: EntityRelationField;
+  evaluations: EntityRelationField;
+}>;
+/**
+ * FlagTargetingRule entity - conditions for targeting.
+ */
+declare const FlagTargetingRuleEntity: EntitySpec<{
+  id: EntityScalarField;
+  flagId: EntityScalarField;
+  name: EntityScalarField;
+  priority: EntityScalarField;
+  enabled: EntityScalarField;
+  attribute: EntityScalarField;
+  operator: EntityEnumField;
+  value: EntityScalarField;
+  rolloutPercentage: EntityScalarField;
+  serveValue: EntityScalarField;
+  serveVariant: EntityScalarField;
+  createdAt: EntityScalarField;
+  updatedAt: EntityScalarField;
+  flag: EntityRelationField;
+}>;
+/**
+ * Experiment entity - A/B test configuration.
+ */
+declare const ExperimentEntity: EntitySpec<{
+  id: EntityScalarField;
+  key: EntityScalarField;
+  name: EntityScalarField;
+  description: EntityScalarField;
+  hypothesis: EntityScalarField;
+  flagId: EntityScalarField;
+  status: EntityEnumField;
+  variants: EntityScalarField;
+  metrics: EntityScalarField;
+  audiencePercentage: EntityScalarField;
+  audienceFilter: EntityScalarField;
+  scheduledStartAt: EntityScalarField;
+  scheduledEndAt: EntityScalarField;
+  startedAt: EntityScalarField;
+  endedAt: EntityScalarField;
+  winningVariant: EntityScalarField;
+  results: EntityScalarField;
+  orgId: EntityScalarField;
+  createdAt: EntityScalarField;
+  updatedAt: EntityScalarField;
+  flag: EntityRelationField;
+  assignments: EntityRelationField;
+}>;
+/**
+ * ExperimentAssignment entity - tracks which variant a subject is assigned to.
+ */
+declare const ExperimentAssignmentEntity: EntitySpec<{
+  id: EntityScalarField;
+  experimentId: EntityScalarField;
+  subjectType: EntityScalarField;
+  subjectId: EntityScalarField;
+  variant: EntityScalarField;
+  bucket: EntityScalarField;
+  context: EntityScalarField;
+  assignedAt: EntityScalarField;
+  experiment: EntityRelationField;
+}>;
+/**
+ * FlagEvaluation entity - evaluation log for analytics.
+ */
+declare const FlagEvaluationEntity: EntitySpec<{
+  id: EntityScalarField;
+  flagId: EntityScalarField;
+  flagKey: EntityScalarField;
+  subjectType: EntityScalarField;
+  subjectId: EntityScalarField;
+  result: EntityScalarField;
+  variant: EntityScalarField;
+  matchedRuleId: EntityScalarField;
+  reason: EntityScalarField;
+  context: EntityScalarField;
+  evaluatedAt: EntityScalarField;
+  flag: EntityRelationField;
+}>;
+/**
+ * All feature flag entities for schema composition.
+ */
+declare const featureFlagEntities: (EntitySpec<{
+  id: EntityScalarField;
+  key: EntityScalarField;
+  name: EntityScalarField;
+  description: EntityScalarField;
+  status: EntityEnumField;
+  defaultValue: EntityScalarField;
+  variants: EntityScalarField;
+  orgId: EntityScalarField;
+  tags: EntityScalarField;
+  metadata: EntityScalarField;
+  createdAt: EntityScalarField;
+  updatedAt: EntityScalarField;
+  targetingRules: EntityRelationField;
+  experiments: EntityRelationField;
+  evaluations: EntityRelationField;
+}> | EntitySpec<{
+  id: EntityScalarField;
+  flagId: EntityScalarField;
+  name: EntityScalarField;
+  priority: EntityScalarField;
+  enabled: EntityScalarField;
+  attribute: EntityScalarField;
+  operator: EntityEnumField;
+  value: EntityScalarField;
+  rolloutPercentage: EntityScalarField;
+  serveValue: EntityScalarField;
+  serveVariant: EntityScalarField;
+  createdAt: EntityScalarField;
+  updatedAt: EntityScalarField;
+  flag: EntityRelationField;
+}> | EntitySpec<{
+  id: EntityScalarField;
+  key: EntityScalarField;
+  name: EntityScalarField;
+  description: EntityScalarField;
+  hypothesis: EntityScalarField;
+  flagId: EntityScalarField;
+  status: EntityEnumField;
+  variants: EntityScalarField;
+  metrics: EntityScalarField;
+  audiencePercentage: EntityScalarField;
+  audienceFilter: EntityScalarField;
+  scheduledStartAt: EntityScalarField;
+  scheduledEndAt: EntityScalarField;
+  startedAt: EntityScalarField;
+  endedAt: EntityScalarField;
+  winningVariant: EntityScalarField;
+  results: EntityScalarField;
+  orgId: EntityScalarField;
+  createdAt: EntityScalarField;
+  updatedAt: EntityScalarField;
+  flag: EntityRelationField;
+  assignments: EntityRelationField;
+}> | EntitySpec<{
+  id: EntityScalarField;
+  experimentId: EntityScalarField;
+  subjectType: EntityScalarField;
+  subjectId: EntityScalarField;
+  variant: EntityScalarField;
+  bucket: EntityScalarField;
+  context: EntityScalarField;
+  assignedAt: EntityScalarField;
+  experiment: EntityRelationField;
+}> | EntitySpec<{
+  id: EntityScalarField;
+  flagId: EntityScalarField;
+  flagKey: EntityScalarField;
+  subjectType: EntityScalarField;
+  subjectId: EntityScalarField;
+  result: EntityScalarField;
+  variant: EntityScalarField;
+  matchedRuleId: EntityScalarField;
+  reason: EntityScalarField;
+  context: EntityScalarField;
+  evaluatedAt: EntityScalarField;
+  flag: EntityRelationField;
+}>)[];
+/**
+ * Module schema contribution for feature flags.
+ */
+declare const featureFlagsSchemaContribution: ModuleSchemaContribution;
+//#endregion
+export { ExperimentAssignmentEntity, ExperimentEntity, ExperimentStatusEnum, FeatureFlagEntity, FlagEvaluationEntity, FlagStatusEnum, FlagTargetingRuleEntity, RuleOperatorEnum, featureFlagEntities, featureFlagsSchemaContribution };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/entities/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AAWa,cAAA,cAKX,EAAA,aAAA;AAKF;AAsBA;AAUA;AA4DE,cA5FW,gBA4FX,EA3EA,aA2EA;;;;cAtEW,sBAKX;;;;cAKW;MA4DX;;;;;;;EA5D4B,KAAA,mBAAA;EAiEjB,IAAA,mBAyDX;EAAA,QAAA,mBAAA;;;;;;;;;;cAzDW;MAyDX;;;;EAzDkC,OAAA,mBAAA;EA8DvB,SAAA,mBA2FX;EAAA,QAAA,iBAAA;;;;;;;;;;;;cA3FW;MA2FX;;;;;;;;;;EA3F2B,cAAA,mBAAA;EAgGhB,gBAAA,mBAuCX;EAAA,cAAA,mBAAA;;;;;;;;;;CAvCqC,CAAA;AA4CvC;;;cA5Ca;MAuCX;;;;;;;;;;;AA+DF;;cA1Da;MAqDX;;;;;;;;;;;;;;;;cAKW;MAMZ;;;;;;;;;;;;;;;;MAN+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWnB,MAAA,mBAAgC;;;;;;;;;;;;;;;;;;;;;cAAhC,gCAAgC"}