@flagwire/evaluate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlagWire contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# `@flagwire/evaluate`
+
+Deterministic local evaluation engine shared by FlagWire's server SDKs. The package includes the
+append-only compatibility vectors used to keep language implementations behaviorally identical.
+
+```ts
+import { evaluateFlag } from "@flagwire/evaluate";
+```
+
+Existing vector files are immutable compatibility history. Add a new vector file for every new
+edge case.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { type EvaluationContext, type JsonValue } from "@flagwire/schema";
+export type { EvaluationContext } from "@flagwire/schema";
+export type EvaluationReason = "ERROR" | "ERROR_MISSING_KEY" | "FALLTHROUGH" | "FLAG_NOT_FOUND" | "OFF" | "REVOKED" | `RULE_MATCH:${string}`;
+export interface EvaluationDetail {
+    variantKey: string | null;
+    value: JsonValue;
+    reason: EvaluationReason;
+}
+export interface EvaluationSnapshot {
+    version: number;
+    flags: Record<string, EvaluationDetail>;
+}
+/** MurmurHash3 x86 32-bit over UTF-8 bytes. */
+export declare function murmur3_32(input: string | Uint8Array, seed?: number): number;
+export declare function bucketFor(contextKey: string, flagKey: string, salt: string): {
+    uint32: number;
+    value: number;
+};
+export declare function evaluateFlag(bundleInput: unknown, flagKey: string, context: EvaluationContext, codeDefault: JsonValue): EvaluationDetail;
+export declare function evaluateBundle(bundleInput: unknown, context: EvaluationContext): EvaluationSnapshot;

package/dist/index.js

@@ -0,0 +1 @@
+import{bundleSchema as y}from"@flagwire/schema";var A=new TextEncoder,b=4294967296;function c(n,r){return n<<r|n>>>32-r}function S(n,r=0){let t=typeof n=="string"?A.encode(n):n,o=t.length-t.length%4,e=r>>>0;for(let i=0;i<o;i+=4){let s=t[i]|t[i+1]<<8|t[i+2]<<16|t[i+3]<<24;s=Math.imul(s,3432918353),s=c(s,15),s=Math.imul(s,461845907),e^=s,e=c(e,13),e=Math.imul(e,5)+3864292196|0}let a=t.length&3;if(a>0){let i=t[o];a>=2&&(i^=t[o+1]<<8),a===3&&(i^=t[o+2]<<16),i=Math.imul(i,3432918353),i=c(i,15),i=Math.imul(i,461845907),e^=i}return e^=t.length,e^=e>>>16,e=Math.imul(e,2246822507),e^=e>>>13,e=Math.imul(e,3266489909),e^=e>>>16,e>>>0}function C(n,r,t){let o=S(`${n}:${r}:${t}`,0);return{uint32:o,value:o/b}}function g(n){let r=/^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(n);if(!r)return;let t=Number(r[1]),o=Number(r[2]),e=Number(r[3]);if(![t,o,e].every(Number.isSafeInteger))return;let a=r[4]?.split(".")??[];if(!a.some(i=>/^\d+$/.test(i)&&i.length>1&&i.startsWith("0")))return{major:t,minor:o,patch:e,prerelease:a}}function F(n,r){for(let o of["major","minor","patch"])if(n[o]!==r[o])return n[o]<r[o]?-1:1;if(n.prerelease.length===0||r.prerelease.length===0)return n.prerelease.length===r.prerelease.length?0:n.prerelease.length===0?1:-1;let t=Math.max(n.prerelease.length,r.prerelease.length);for(let o=0;o<t;o+=1){let e=n.prerelease[o],a=r.prerelease[o];if(e===void 0||a===void 0)return e===a?0:e===void 0?-1:1;if(e===a)continue;let i=/^\d+$/.test(e),s=/^\d+$/.test(a);return i&&s?e.length!==a.length?e.length<a.length?-1:1:e<a?-1:1:i!==s?i?-1:1:e<a?-1:1}return 0}function v(n){if(typeof n=="number")return Number.isFinite(n)?n:void 0;if(typeof n!="string"||n.trim()==="")return;let r=Number(n);return Number.isFinite(r)?r:void 0}function N(n,r,t){try{switch(n){case"eq":return Array.isArray(r)||typeof r!=typeof t?"error":r===t?"match":"no-match";case"neq":return Array.isArray(r)||typeof r!=typeof t?"error":r!==t?"match":"no-match";case"in":return Array.isArray(r)||typeof r!=typeof t?"error":r===t?"match":"no-match";case"contains":return typeof r=="string"&&typeof t=="string"||Array.isArray(r)&&typeof t=="string"?r.includes(t)?"match":"no-match":"error";case"startsWith":return typeof r=="string"&&typeof t=="string"?r.startsWith(t)?"match":"no-match":"error";case"endsWith":return typeof r=="string"&&typeof t=="string"?r.endsWith(t)?"match":"no-match":"error";case"gt":case"gte":case"lt":case"lte":{if(Array.isArray(r))return"error";let o=v(r),e=v(t);return o===void 0||e===void 0?"error":(n==="gt"?o>e:n==="gte"?o>=e:n==="lt"?o<e:o<=e)?"match":"no-match"}case"semverEq":case"semverGt":case"semverLt":{if(typeof r!="string"||typeof t!="string")return"error";let o=g(r),e=g(t);if(!o||!e)return"error";let a=F(o,e);return(n==="semverEq"?a===0:n==="semverGt"?a>0:a<0)?"match":"no-match"}case"regex":return typeof r!="string"||typeof t!="string"||t.length>256?"error":new RegExp(t).test(r)?"match":"no-match"}return"error"}catch{return"error"}}function k(n,r,t,o){let e=r[n];if(!e||o.has(n))return"error";let a=new Set(o);a.add(n);let i=!1;for(let s of e){let u=!0;for(let R of s.clauses){let h=p(R,r,t,a);if(h==="error"){i=!0,u=!1;break}if(h==="no-match"){u=!1;break}}if(u)return"match"}return i?"error":"no-match"}function p(n,r,t,o){let e=!1,a=!1;if(n.op==="segment")for(let i of n.values){if(typeof i!="string"||!r[i]){a=!0;continue}let s=k(i,r,t,o);if(s==="error"){a=!0;continue}if(s==="match"){e=!0;break}}else{let i=t.attributes?.[n.attr];if(i===void 0)return"error";for(let s of n.values){let u=N(n.op,i,s);if(u==="error"){a=!0;continue}if(u==="match"){e=!0;break}}}return!e&&a?"error":(n.negate&&(e=!e),e?"match":"no-match")}function l(n,r){return{variantKey:null,value:n,reason:r}}function m(n,r,t,o){let e=n.variants[r];return e?{variantKey:e.key,value:e.value,reason:t}:l(o,"ERROR")}function f(n,r,t){return m(n,n.offVariant,r,t)}function d(n,r,t,o,e,a){if("variant"in o)return m(n,o.variant,e,a);if(!t.key)return f(n,"ERROR_MISSING_KEY",a);let i=C(t.key,r,n.salt).uint32,s=0;for(let u of o.rollout.variations)if(s+=u.weight,i*1e5<s*b)return m(n,u.variant,e,a);return f(n,"ERROR",a)}function E(n,r,t,o,e){try{if(!t.on)return f(t,"OFF",e);for(let a of t.rules){let i=!0;for(let s of a.clauses)if(p(s,n.segments,o,new Set)!=="match"){i=!1;break}if(i)return d(t,r,o,a.serve,`RULE_MATCH:${a.id}`,e)}return d(t,r,o,t.fallthrough,"FALLTHROUGH",e)}catch{return f(t,"ERROR",e)}}function M(n,r,t,o){let e=y.safeParse(n);if(!e.success)return l(o,"ERROR");if(e.data.revoked)return l(o,"REVOKED");let a=e.data.flags[r];return a?E(e.data,r,a,t,o):l(o,"FLAG_NOT_FOUND")}function _(n,r){let t=y.safeParse(n);if(!t.success)return{version:0,flags:{}};let o=t.data;if(o.revoked)return{version:o.version,flags:{}};let e={};for(let[a,i]of Object.entries(o.flags)){let s=i.variants[i.offVariant]?.value??null;e[a]=E(o,a,i,r,s)}return{version:o.version,flags:e}}export{C as bucketFor,_ as evaluateBundle,M as evaluateFlag,S as murmur3_32};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@flagwire/evaluate",
+  "version": "0.1.0",
+  "description": "Deterministic local evaluation engine for FlagWire",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "vectors"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vectors/*": "./vectors/*"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flagwire/flagwire-js.git",
+    "directory": "packages/evaluate"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@flagwire/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-package-dist.mjs && tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --minify --format=esm --platform=neutral --target=es2022 --external:@flagwire/schema --outfile=dist/index.js",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/vectors/.gitkeep

@@ -0,0 +1 @@
+

package/vectors/bucketing.json

@@ -0,0 +1,86 @@
+[
+  {
+    "contextKey": "user-1",
+    "flagKey": "new-checkout",
+    "salt": "0123456789abcdef",
+    "expectedBucketUint32": 1270273690,
+    "expectedFloat12dp": 0.295758640859
+  },
+  {
+    "contextKey": "user-2",
+    "flagKey": "new-checkout",
+    "salt": "0123456789abcdef",
+    "expectedBucketUint32": 2494462029,
+    "expectedFloat12dp": 0.580787199782
+  },
+  {
+    "contextKey": "",
+    "flagKey": "new-checkout",
+    "salt": "0123456789abcdef",
+    "expectedBucketUint32": 2569104276,
+    "expectedFloat12dp": 0.598166202195
+  },
+  {
+    "contextKey": "🚀",
+    "flagKey": "launch",
+    "salt": "fedcba9876543210",
+    "expectedBucketUint32": 2390768489,
+    "expectedFloat12dp": 0.556644166121
+  },
+  {
+    "contextKey": "café",
+    "flagKey": "pricing.test",
+    "salt": "a1b2c3d4e5f60718",
+    "expectedBucketUint32": 953215369,
+    "expectedFloat12dp": 0.221937747905
+  },
+  {
+    "contextKey": "same",
+    "flagKey": "flag-a",
+    "salt": "0000000000000000",
+    "expectedBucketUint32": 1685671660,
+    "expectedFloat12dp": 0.392476017587
+  },
+  {
+    "contextKey": "same",
+    "flagKey": "flag-b",
+    "salt": "0000000000000000",
+    "expectedBucketUint32": 4153084138,
+    "expectedFloat12dp": 0.966965252999
+  },
+  {
+    "contextKey": "same",
+    "flagKey": "flag-a",
+    "salt": "ffffffffffffffff",
+    "expectedBucketUint32": 1774884951,
+    "expectedFloat12dp": 0.413247605553
+  },
+  {
+    "contextKey": "tenant:user:123",
+    "flagKey": "payments-v2",
+    "salt": "1234567890abcdef",
+    "expectedBucketUint32": 587700822,
+    "expectedFloat12dp": 0.136834760662
+  },
+  {
+    "contextKey": "A",
+    "flagKey": "a",
+    "salt": "1111111111111111",
+    "expectedBucketUint32": 1610235386,
+    "expectedFloat12dp": 0.374912141357
+  },
+  {
+    "contextKey": "very-long-context-key-0123456789-abcdefghijklmnopqrstuvwxyz",
+    "flagKey": "long-flag-key.test",
+    "salt": "abcdefabcdefabcd",
+    "expectedBucketUint32": 2704953973,
+    "expectedFloat12dp": 0.629796174588
+  },
+  {
+    "contextKey": "你好",
+    "flagKey": "i18n-rollout",
+    "salt": "9999999999999999",
+    "expectedBucketUint32": 3734192613,
+    "expectedFloat12dp": 0.869434469612
+  }
+]

package/vectors/eval/fail-safe-01.json

@@ -0,0 +1,42 @@
+{
+  "name": "disabled flag serves off variant",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": false,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 1
+        },
+        "rules": []
+      }
+    }
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": "off",
+    "value": false,
+    "reason": "OFF"
+  }
+}

package/vectors/eval/fail-safe-02.json

@@ -0,0 +1,42 @@
+{
+  "name": "missing flag uses code default",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "another-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 0
+        },
+        "rules": []
+      }
+    }
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": null,
+    "value": "CODE_DEFAULT",
+    "reason": "FLAG_NOT_FOUND"
+  }
+}

package/vectors/eval/fail-safe-03.json

@@ -0,0 +1,20 @@
+{
+  "name": "revoked bundle uses code default",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 8,
+    "publishedAt": 1700000000001,
+    "revoked": true,
+    "segments": {},
+    "flags": {}
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": null,
+    "value": "CODE_DEFAULT",
+    "reason": "REVOKED"
+  }
+}

package/vectors/eval/fail-safe-04.json

@@ -0,0 +1,42 @@
+{
+  "name": "unknown bundle format uses code default",
+  "bundle": {
+    "fmt": 2,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 0
+        },
+        "rules": []
+      }
+    }
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": null,
+    "value": "CODE_DEFAULT",
+    "reason": "ERROR"
+  }
+}

package/vectors/eval/fail-safe-05.json

@@ -0,0 +1,42 @@
+{
+  "name": "invalid variant reference uses code default",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 99
+        },
+        "rules": []
+      }
+    }
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": null,
+    "value": "CODE_DEFAULT",
+    "reason": "ERROR"
+  }
+}

package/vectors/eval/fail-safe-06.json

@@ -0,0 +1,60 @@
+{
+  "name": "nonnumeric comparison is a false clause",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 0
+        },
+        "rules": [
+          {
+            "id": "rule-1",
+            "clauses": [
+              {
+                "attr": "score",
+                "op": "gt",
+                "values": [5],
+                "negate": false
+              }
+            ],
+            "serve": {
+              "variant": 1
+            }
+          }
+        ]
+      }
+    }
+  },
+  "context": {
+    "key": "u",
+    "attributes": {
+      "score": "five"
+    }
+  },
+  "expected": {
+    "variantKey": "off",
+    "value": false,
+    "reason": "FALLTHROUGH"
+  }
+}

package/vectors/eval/fail-safe-07.json

@@ -0,0 +1,42 @@
+{
+  "name": "normal fallthrough serves configured variant",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 1
+        },
+        "rules": []
+      }
+    }
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": "on",
+    "value": true,
+    "reason": "FALLTHROUGH"
+  }
+}

package/vectors/eval/fail-safe-08.json

@@ -0,0 +1,57 @@
+{
+  "name": "empty attributes do not throw",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 0
+        },
+        "rules": [
+          {
+            "id": "rule-1",
+            "clauses": [
+              {
+                "attr": "plan",
+                "op": "eq",
+                "values": ["pro"],
+                "negate": false
+              }
+            ],
+            "serve": {
+              "variant": 1
+            }
+          }
+        ]
+      }
+    }
+  },
+  "context": {
+    "key": "u"
+  },
+  "expected": {
+    "variantKey": "off",
+    "value": false,
+    "reason": "FALLTHROUGH"
+  }
+}

package/vectors/eval/operators-01.json

@@ -0,0 +1,60 @@
+{
+  "name": "eq matches equal strings",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 0
+        },
+        "rules": [
+          {
+            "id": "rule-1",
+            "clauses": [
+              {
+                "attr": "value",
+                "op": "eq",
+                "values": ["pro"],
+                "negate": false
+              }
+            ],
+            "serve": {
+              "variant": 1
+            }
+          }
+        ]
+      }
+    }
+  },
+  "context": {
+    "key": "u",
+    "attributes": {
+      "value": "pro"
+    }
+  },
+  "expected": {
+    "variantKey": "on",
+    "value": true,
+    "reason": "RULE_MATCH:rule-1"
+  }
+}

package/vectors/eval/operators-02.json

@@ -0,0 +1,60 @@
+{
+  "name": "eq does not match unequal strings",
+  "bundle": {
+    "fmt": 1,
+    "envId": "env_test",
+    "version": 7,
+    "publishedAt": 1700000000000,
+    "revoked": false,
+    "segments": {},
+    "flags": {
+      "test-flag": {
+        "type": "boolean",
+        "version": 3,
+        "salt": "0123456789abcdef",
+        "on": true,
+        "variants": [
+          {
+            "key": "off",
+            "value": false
+          },
+          {
+            "key": "on",
+            "value": true
+          }
+        ],
+        "offVariant": 0,
+        "fallthrough": {
+          "variant": 0
+        },
+        "rules": [
+          {
+            "id": "rule-1",
+            "clauses": [
+              {
+                "attr": "value",
+                "op": "eq",
+                "values": ["pro"],
+                "negate": false
+              }
+            ],
+            "serve": {
+              "variant": 1
+            }
+          }
+        ]
+      }
+    }
+  },
+  "context": {
+    "key": "u",
+    "attributes": {
+      "value": "free"
+    }
+  },
+  "expected": {
+    "variantKey": "off",
+    "value": false,
+    "reason": "FALLTHROUGH"
+  }
+}