@contractspec/example.personalization 3.7.7 → 3.7.12

package/.turbo/turbo-build.log

@@ -2,40 +2,46 @@ $ contractspec-bun-build prebuild
 $ bun run prebuild && bun run build:bundle && bun run build:types
 $ contractspec-bun-build prebuild
 $ contractspec-bun-build transpile
-[contractspec-bun-build] transpile target=bun root=src entries=8 noBundle=false
-Bundled 8 modules in 5ms
+[contractspec-bun-build] transpile target=bun root=src entries=10 noBundle=false
+Bundled 10 modules in 13ms
 
-  ./behavior-tracking.js            1.33 KB  (entry point)
-  ./index.js                        7.60 KB  (entry point)
-  docs/index.js                     1.48 KB  (entry point)
-  docs/personalization.docblock.js  1.48 KB  (entry point)
-  ./example.js                      0.99 KB  (entry point)
-  ./overlay-customization.js        1.53 KB  (entry point)
-  ./personalization.feature.js      0.71 KB  (entry point)
-  ./workflow-extension.js           1.59 KB  (entry point)
+  ./behavior-tracking.js             1.33 KB   (entry point)
+  ./index.js                         10.57 KB  (entry point)
+  ./personalization.theme.js         1.35 KB   (entry point)
+  ./workflow-extension.js            1.59 KB   (entry point)
+  docs/index.js                      1.48 KB   (entry point)
+  docs/personalization.docblock.js   1.48 KB   (entry point)
+  ./example.js                       0.99 KB   (entry point)
+  ./overlay-customization.js         1.53 KB   (entry point)
+  ./personalization.experiment.js    1.60 KB   (entry point)
+  ./personalization.feature.js       0.71 KB   (entry point)
 
-[contractspec-bun-build] transpile target=node root=src entries=8 noBundle=false
-Bundled 8 modules in 5ms
+[contractspec-bun-build] transpile target=node root=src entries=10 noBundle=false
+Bundled 10 modules in 12ms
 
-  ./behavior-tracking.js            1.32 KB  (entry point)
-  ./index.js                        7.59 KB  (entry point)
-  docs/index.js                     1.47 KB  (entry point)
-  docs/personalization.docblock.js  1.47 KB  (entry point)
-  ./example.js                      0.99 KB  (entry point)
-  ./overlay-customization.js        1.52 KB  (entry point)
-  ./personalization.feature.js      0.70 KB  (entry point)
-  ./workflow-extension.js           1.58 KB  (entry point)
+  ./behavior-tracking.js             1.32 KB   (entry point)
+  ./index.js                         10.56 KB  (entry point)
+  ./personalization.theme.js         1.34 KB   (entry point)
+  ./workflow-extension.js            1.58 KB   (entry point)
+  docs/index.js                      1.47 KB   (entry point)
+  docs/personalization.docblock.js   1.47 KB   (entry point)
+  ./example.js                       0.99 KB   (entry point)
+  ./overlay-customization.js         1.52 KB   (entry point)
+  ./personalization.experiment.js    1.60 KB   (entry point)
+  ./personalization.feature.js       0.70 KB   (entry point)
 
-[contractspec-bun-build] transpile target=browser root=src entries=8 noBundle=false
-Bundled 8 modules in 17ms
+[contractspec-bun-build] transpile target=browser root=src entries=10 noBundle=false
+Bundled 10 modules in 8ms
 
-  ./behavior-tracking.js            1.32 KB  (entry point)
-  ./index.js                        7.59 KB  (entry point)
-  docs/index.js                     1.47 KB  (entry point)
-  docs/personalization.docblock.js  1.47 KB  (entry point)
-  ./example.js                      0.99 KB  (entry point)
-  ./overlay-customization.js        1.52 KB  (entry point)
-  ./personalization.feature.js      0.70 KB  (entry point)
-  ./workflow-extension.js           1.58 KB  (entry point)
+  ./behavior-tracking.js             1.32 KB   (entry point)
+  ./index.js                         10.56 KB  (entry point)
+  ./personalization.theme.js         1.34 KB   (entry point)
+  ./workflow-extension.js            1.58 KB   (entry point)
+  docs/index.js                      1.47 KB   (entry point)
+  docs/personalization.docblock.js   1.47 KB   (entry point)
+  ./example.js                       0.99 KB   (entry point)
+  ./overlay-customization.js         1.52 KB   (entry point)
+  ./personalization.experiment.js    1.60 KB   (entry point)
+  ./personalization.feature.js       0.70 KB   (entry point)
 
 $ contractspec-bun-build types

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @contractspec/example.personalization
 
+## 3.7.12
+
+### Patch Changes
+
+- Updated dependencies [81256ea]
+- Updated dependencies [2619dd8]
+- Updated dependencies [81256ea]
+- Updated dependencies [a4489bb]
+- Updated dependencies [9cb304e]
+  - @contractspec/lib.contracts-spec@5.0.0
+  - @contractspec/lib.workflow-composer@3.7.12
+  - @contractspec/lib.overlay-engine@3.7.12
+  - @contractspec/lib.personalization@6.0.12
+
+## 3.7.11
+
+### Patch Changes
+
+- fix: release
+- Updated dependencies
+  - @contractspec/lib.workflow-composer@3.7.11
+  - @contractspec/lib.personalization@6.0.11
+  - @contractspec/lib.contracts-spec@4.1.3
+  - @contractspec/lib.overlay-engine@3.7.11
+  - @contractspec/lib.logger@3.7.9
+
+## 3.7.10
+
+### Patch Changes
+
+- 1a44cb6: feat: improve examples to increase coverage of Contracts type
+- Updated dependencies [1a44cb6]
+  - @contractspec/lib.workflow-composer@3.7.10
+  - @contractspec/lib.personalization@6.0.10
+  - @contractspec/lib.contracts-spec@4.1.2
+  - @contractspec/lib.overlay-engine@3.7.10
+  - @contractspec/lib.logger@3.7.8
+
+## 3.7.9
+
+### Patch Changes
+
+- fix: release
+- Updated dependencies
+  - @contractspec/lib.workflow-composer@3.7.9
+  - @contractspec/lib.personalization@6.0.9
+  - @contractspec/lib.contracts-spec@4.1.1
+  - @contractspec/lib.overlay-engine@3.7.9
+  - @contractspec/lib.logger@3.7.7
+
 ## 3.7.6
 
 ### Patch Changes
@@ -483,6 +533,7 @@
 - 7f3203a: fix: make workspace test runs resilient when packages have no tests
 
   Updates package test scripts to pass cleanly when no matching test files exist:
+
   - Uses `bun test --pass-with-no-tests` in Bun-based packages that currently ship without test files.
   - Uses `jest --passWithNoTests` for the UI kit web package.
   - Adds `.vscode-test.mjs` for `vscode-contractspec` so VS Code extension test runs have an explicit config and stop failing on missing default configuration.
@@ -901,14 +952,17 @@
   feat: Contract layers support (features, examples, app-configs)
 
   ### New CLI Commands
+
   - `contractspec list layers` - List all contract layers with filtering
 
   ### Enhanced Commands
+
   - `contractspec ci` - New `layers` check category validates features/examples/config
   - `contractspec doctor` - New `layers` health checks
   - `contractspec integrity` - Now shows layer statistics
 
   ### New APIs
+
   - `discoverLayers()` - Scan workspace for all layer files
   - `scanExampleSource()` - Parse ExampleSpec from source code
   - `isExampleFile()` - Check if file is an example spec

package/README.md

@@ -7,11 +7,12 @@ Website: https://contractspec.io
 ## What This Demonstrates
 
 - Behavior tracking integration pattern.
+- Canonical `experiment` export via `PersonalizationExperiment`.
 - Overlay customization via overlay-engine.
+- Canonical `theme` export via `PersonalizationTheme`.
 - Workflow extension via workflow-composer.
 - Multi-lib composition in a single example.
 - `src/docs/` contains docblocks and documentation-facing exports.
-- `src/docs/` contains docblocks and documentation-facing exports.
 
 ## Running Locally
 
@@ -32,7 +33,9 @@ Use `@contractspec/example.personalization` as a reference implementation, or im
 - `src/example.ts` is the runnable example entrypoint.
 - `src/index.ts` is the root public barrel and package entrypoint.
 - `src/overlay-customization.ts` is part of the package's public or composition surface.
+- `src/personalization.experiment.ts` defines the exported experiment spec.
 - `src/personalization.feature.ts` defines a feature entrypoint.
+- `src/personalization.theme.ts` defines the exported theme spec.
 - `src/workflow-extension.ts` is part of the package's public or composition surface.
 
 ## Public Entry Points
@@ -43,8 +46,11 @@ Use `@contractspec/example.personalization` as a reference implementation, or im
 - Export `./docs/personalization.docblock` resolves through `./src/docs/personalization.docblock.ts`.
 - Export `./example` resolves through `./src/example.ts`.
 - Export `./overlay-customization` resolves through `./src/overlay-customization.ts`.
+- Export `./personalization.experiment` resolves through `./src/personalization.experiment.ts`.
 - Export `./personalization.feature` resolves through `./src/personalization.feature.ts`.
+- Export `./personalization.theme` resolves through `./src/personalization.theme.ts`.
 - Export `./workflow-extension` resolves through `./src/workflow-extension.ts`.
+- The package publishes 9 total export subpaths; keep docs aligned with `package.json`.
 
 ## Local Commands
 

package/dist/browser/index.js

@@ -162,6 +162,66 @@ async function runOverlayCustomizationExample() {
   logger2.info("Overlay applied", { fields: result.target.fields });
 }
 
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+
 // src/personalization.feature.ts
 import { defineFeature } from "@contractspec/lib.contracts-spec";
 var PersonalizationFeature = defineFeature({
@@ -182,8 +242,70 @@ var PersonalizationFeature = defineFeature({
   ]
 });
 
+// src/personalization.theme.ts
+import {
+  OwnersEnum as OwnersEnum2,
+  StabilityEnum as StabilityEnum2
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum2.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum2.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+
 // src/workflow-extension.ts
-import { StabilityEnum } from "@contractspec/lib.contracts-spec";
+import { StabilityEnum as StabilityEnum3 } from "@contractspec/lib.contracts-spec";
 import { Logger as Logger3, LogLevel as LogLevel3 } from "@contractspec/lib.logger";
 import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 var logger3 = new Logger3({
@@ -200,7 +322,7 @@ var BaseWorkflow = {
     tags: [],
     description: "",
     domain: "billing",
-    stability: StabilityEnum.Stable
+    stability: StabilityEnum3.Stable
   },
   definition: {
     steps: [
@@ -244,5 +366,7 @@ export {
   logTenantWorkflowSteps,
   example_default as example,
   composeTenantWorkflowExample,
-  PersonalizationFeature
+  PersonalizationTheme,
+  PersonalizationFeature,
+  PersonalizationExperiment
 };

package/dist/browser/personalization.experiment.js

@@ -0,0 +1,62 @@
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+export {
+  PersonalizationExperiment
+};

package/dist/browser/personalization.theme.js

@@ -0,0 +1,64 @@
+// src/personalization.theme.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+export {
+  PersonalizationTheme
+};

package/dist/contracts.test.d.ts

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

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './behavior-tracking';
 export { default as example } from './example';
 export * from './overlay-customization';
+export * from './personalization.experiment';
 export * from './personalization.feature';
+export * from './personalization.theme';
 export * from './workflow-extension';
 import './docs';

package/dist/index.js

@@ -163,6 +163,66 @@ async function runOverlayCustomizationExample() {
   logger2.info("Overlay applied", { fields: result.target.fields });
 }
 
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+
 // src/personalization.feature.ts
 import { defineFeature } from "@contractspec/lib.contracts-spec";
 var PersonalizationFeature = defineFeature({
@@ -183,8 +243,70 @@ var PersonalizationFeature = defineFeature({
   ]
 });
 
+// src/personalization.theme.ts
+import {
+  OwnersEnum as OwnersEnum2,
+  StabilityEnum as StabilityEnum2
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum2.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum2.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+
 // src/workflow-extension.ts
-import { StabilityEnum } from "@contractspec/lib.contracts-spec";
+import { StabilityEnum as StabilityEnum3 } from "@contractspec/lib.contracts-spec";
 import { Logger as Logger3, LogLevel as LogLevel3 } from "@contractspec/lib.logger";
 import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 var logger3 = new Logger3({
@@ -201,7 +323,7 @@ var BaseWorkflow = {
     tags: [],
     description: "",
     domain: "billing",
-    stability: StabilityEnum.Stable
+    stability: StabilityEnum3.Stable
   },
   definition: {
     steps: [
@@ -245,5 +367,7 @@ export {
   logTenantWorkflowSteps,
   example_default as example,
   composeTenantWorkflowExample,
-  PersonalizationFeature
+  PersonalizationTheme,
+  PersonalizationFeature,
+  PersonalizationExperiment
 };

package/dist/node/index.js

@@ -162,6 +162,66 @@ async function runOverlayCustomizationExample() {
   logger2.info("Overlay applied", { fields: result.target.fields });
 }
 
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+
 // src/personalization.feature.ts
 import { defineFeature } from "@contractspec/lib.contracts-spec";
 var PersonalizationFeature = defineFeature({
@@ -182,8 +242,70 @@ var PersonalizationFeature = defineFeature({
   ]
 });
 
+// src/personalization.theme.ts
+import {
+  OwnersEnum as OwnersEnum2,
+  StabilityEnum as StabilityEnum2
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum2.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum2.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+
 // src/workflow-extension.ts
-import { StabilityEnum } from "@contractspec/lib.contracts-spec";
+import { StabilityEnum as StabilityEnum3 } from "@contractspec/lib.contracts-spec";
 import { Logger as Logger3, LogLevel as LogLevel3 } from "@contractspec/lib.logger";
 import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 var logger3 = new Logger3({
@@ -200,7 +322,7 @@ var BaseWorkflow = {
     tags: [],
     description: "",
     domain: "billing",
-    stability: StabilityEnum.Stable
+    stability: StabilityEnum3.Stable
   },
   definition: {
     steps: [
@@ -244,5 +366,7 @@ export {
   logTenantWorkflowSteps,
   example_default as example,
   composeTenantWorkflowExample,
-  PersonalizationFeature
+  PersonalizationTheme,
+  PersonalizationFeature,
+  PersonalizationExperiment
 };

package/dist/node/personalization.experiment.js

@@ -0,0 +1,62 @@
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+export {
+  PersonalizationExperiment
+};

package/dist/node/personalization.theme.js

@@ -0,0 +1,64 @@
+// src/personalization.theme.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+export {
+  PersonalizationTheme
+};

package/dist/personalization.experiment.d.ts

@@ -0,0 +1,2 @@
+import type { ExperimentSpec } from '@contractspec/lib.contracts-spec/experiments/spec';
+export declare const PersonalizationExperiment: ExperimentSpec;

package/dist/personalization.experiment.js

@@ -0,0 +1,63 @@
+// @bun
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+export {
+  PersonalizationExperiment
+};

package/dist/personalization.theme.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeSpec } from '@contractspec/lib.contracts-spec/themes';
+export declare const PersonalizationTheme: ThemeSpec;

package/dist/personalization.theme.js

@@ -0,0 +1,65 @@
+// @bun
+// src/personalization.theme.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+export {
+  PersonalizationTheme
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.personalization",
-  "version": "3.7.7",
+  "version": "3.7.12",
   "description": "Personalization examples: behavior tracking, overlay customization, workflow extension.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -47,6 +47,13 @@
       "node": "./dist/node/overlay-customization.js",
       "default": "./dist/overlay-customization.js"
     },
+    "./personalization.experiment": {
+      "types": "./dist/personalization.experiment.d.ts",
+      "browser": "./dist/browser/personalization.experiment.js",
+      "bun": "./dist/personalization.experiment.js",
+      "node": "./dist/node/personalization.experiment.js",
+      "default": "./dist/personalization.experiment.js"
+    },
     "./personalization.feature": {
       "types": "./dist/personalization.feature.d.ts",
       "browser": "./dist/browser/personalization.feature.js",
@@ -54,6 +61,13 @@
       "node": "./dist/node/personalization.feature.js",
       "default": "./dist/personalization.feature.js"
     },
+    "./personalization.theme": {
+      "types": "./dist/personalization.theme.d.ts",
+      "browser": "./dist/browser/personalization.theme.js",
+      "bun": "./dist/personalization.theme.js",
+      "node": "./dist/node/personalization.theme.js",
+      "default": "./dist/personalization.theme.js"
+    },
     "./workflow-extension": {
       "types": "./dist/workflow-extension.d.ts",
       "browser": "./dist/browser/workflow-extension.js",
@@ -78,16 +92,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.personalization": "6.0.7",
-    "@contractspec/lib.overlay-engine": "3.7.7",
-    "@contractspec/lib.workflow-composer": "3.7.7",
-    "@contractspec/lib.contracts-spec": "4.0.0",
-    "@contractspec/lib.logger": "3.7.6"
+    "@contractspec/lib.personalization": "6.0.12",
+    "@contractspec/lib.overlay-engine": "3.7.12",
+    "@contractspec/lib.workflow-composer": "3.7.12",
+    "@contractspec/lib.contracts-spec": "5.0.0",
+    "@contractspec/lib.logger": "3.7.9"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.9",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.bun": "3.7.9"
   },
   "publishConfig": {
     "access": "public",
@@ -134,6 +148,13 @@
         "node": "./dist/node/overlay-customization.js",
         "default": "./dist/overlay-customization.js"
       },
+      "./personalization.experiment": {
+        "types": "./dist/personalization.experiment.d.ts",
+        "browser": "./dist/browser/personalization.experiment.js",
+        "bun": "./dist/personalization.experiment.js",
+        "node": "./dist/node/personalization.experiment.js",
+        "default": "./dist/personalization.experiment.js"
+      },
       "./personalization.feature": {
         "types": "./dist/personalization.feature.d.ts",
         "browser": "./dist/browser/personalization.feature.js",
@@ -141,6 +162,13 @@
         "node": "./dist/node/personalization.feature.js",
         "default": "./dist/personalization.feature.js"
       },
+      "./personalization.theme": {
+        "types": "./dist/personalization.theme.d.ts",
+        "browser": "./dist/browser/personalization.theme.js",
+        "bun": "./dist/personalization.theme.js",
+        "node": "./dist/node/personalization.theme.js",
+        "default": "./dist/personalization.theme.js"
+      },
       "./workflow-extension": {
         "types": "./dist/workflow-extension.d.ts",
         "browser": "./dist/browser/workflow-extension.js",

package/src/contracts.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test';
+import {
+	PersonalizationExperiment,
+	PersonalizationFeature,
+	PersonalizationTheme,
+} from './index';
+
+describe('@contractspec/example.personalization', () => {
+	test('exports the canonical experiment and theme', () => {
+		expect(PersonalizationExperiment.meta.key).toBe(
+			'personalization.experiment.overlay-copy'
+		);
+		expect(PersonalizationExperiment.variants).toHaveLength(2);
+		expect(PersonalizationTheme.meta.key).toBe(
+			'personalization.theme.guided-onboarding'
+		);
+		expect(PersonalizationTheme.overrides).toHaveLength(1);
+		expect(PersonalizationFeature.meta.key).toBe('personalization');
+	});
+});

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './behavior-tracking';
 export { default as example } from './example';
 export * from './overlay-customization';
+export * from './personalization.experiment';
 export * from './personalization.feature';
+export * from './personalization.theme';
 export * from './workflow-extension';
 import './docs';

package/src/personalization.experiment.ts

@@ -0,0 +1,61 @@
+import type { ExperimentSpec } from '@contractspec/lib.contracts-spec/experiments/spec';
+import {
+	OwnersEnum,
+	StabilityEnum,
+} from '@contractspec/lib.contracts-spec/ownership';
+
+export const PersonalizationExperiment: ExperimentSpec = {
+	meta: {
+		key: 'personalization.experiment.overlay-copy',
+		version: '1.0.0',
+		title: 'Personalization Overlay Copy Experiment',
+		description:
+			'Tests a control onboarding copy against a personalized overlay variant.',
+		domain: 'personalization',
+		owners: [OwnersEnum.PlatformCore],
+		tags: ['personalization', 'experiment', 'overlay'],
+		stability: StabilityEnum.Experimental,
+	},
+	controlVariant: 'control',
+	variants: [
+		{
+			id: 'control',
+			key: 'control',
+			description: 'Default onboarding copy and standard workflow.',
+		},
+		{
+			id: 'personalized-overlay',
+			key: 'personalized-overlay',
+			description: 'Personalized copy with a branded theme override.',
+			overrides: [
+				{
+					type: 'theme',
+					target: 'personalization.theme.guided-onboarding',
+					version: '1.0.0',
+				},
+				{
+					type: 'workflow',
+					target: 'billing.invoiceApproval',
+					version: '1.0.0',
+				},
+			],
+		},
+	],
+	allocation: {
+		type: 'sticky',
+		attribute: 'userId',
+		salt: 'personalization-overlay-copy',
+	},
+	successMetrics: [
+		{
+			key: 'checklist-completion-rate',
+			telemetryEvent: {
+				key: 'personalization.assignment.completed',
+				version: '1.0.0',
+			},
+			aggregation: 'count',
+			target: 1,
+		},
+	],
+	tags: ['personalization', 'experiment'],
+};

package/src/personalization.theme.ts

@@ -0,0 +1,63 @@
+import {
+	OwnersEnum,
+	StabilityEnum,
+} from '@contractspec/lib.contracts-spec/ownership';
+import type { ThemeSpec } from '@contractspec/lib.contracts-spec/themes';
+
+export const PersonalizationTheme: ThemeSpec = {
+	meta: {
+		key: 'personalization.theme.guided-onboarding',
+		version: '1.0.0',
+		title: 'Guided Onboarding Theme',
+		description:
+			'Theme tokens used when the personalized onboarding experience is active.',
+		domain: 'personalization',
+		owners: [OwnersEnum.PlatformCore],
+		tags: ['personalization', 'theme', 'onboarding'],
+		stability: StabilityEnum.Experimental,
+		scopes: ['tenant', 'user'],
+	},
+	tokens: {
+		colors: {
+			surface: { value: '#FCF6E8' },
+			accent: { value: '#C8742A' },
+			text: { value: '#2F2419' },
+		},
+		radii: {
+			card: { value: 18 },
+		},
+		space: {
+			panel: { value: 24 },
+		},
+		typography: {
+			body: { value: 16 },
+			title: { value: 28 },
+		},
+		motion: {
+			stagger: { value: '180ms' },
+		},
+	},
+	components: [
+		{
+			component: 'OnboardingChecklist',
+			variants: {
+				guided: {
+					props: {
+						emphasis: 'warm',
+					},
+				},
+			},
+		},
+	],
+	overrides: [
+		{
+			scope: 'tenant',
+			target: 'tenant:acme',
+			tokens: {
+				colors: {
+					accent: { value: '#8A4B12' },
+				},
+			},
+		},
+	],
+};