@traffical/sdk-spec 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Traffical
+
+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,108 @@
+# Traffical SDK Specification
+
+Language-agnostic specifications for implementing Traffical SDKs.
+
+## Overview
+
+This repository contains:
+
+- **JSON Schemas** - Type definitions for configuration bundles and events
+- **Test Vectors** - Deterministic test fixtures for validating SDK implementations
+
+All Traffical SDKs must implement these specifications to ensure consistent behavior across languages.
+
+## Schemas
+
+### `config-bundle.schema.json`
+
+The complete configuration bundle that SDKs fetch and cache. Contains:
+
+- Organization and project identifiers
+- Hashing configuration (unit key, bucket count)
+- Parameters with defaults and layer membership
+- Layers with policies and allocations
+- Conditions for targeting
+
+### `events.schema.json`
+
+Event payloads sent to the Traffical API:
+
+- Exposure events (when a user is assigned to a variant)
+- Track events (custom user actions)
+
+### `traffical-config.schema.json`
+
+Local project configuration file (`.traffical/config.yaml`) schema.
+
+## Test Vectors
+
+The `test-vectors/` directory contains deterministic test fixtures for validating SDK implementations.
+
+### Purpose
+
+All Traffical SDKs must produce identical results for the same inputs:
+
+1. **Hashing consistency** - FNV-1a hash produces the same bucket across all implementations
+2. **Resolution correctness** - Parameter resolution follows the layered priority system
+3. **Condition evaluation** - Context predicates are evaluated identically
+
+### Fixture Structure
+
+```
+test-vectors/
+├── fixtures/
+│   ├── bundle_*.json        # Config bundles to test against
+│   └── expected_*.json      # Expected outputs for each bundle
+└── README.md
+```
+
+### Running Tests
+
+Each SDK implementation should:
+
+1. Load the bundle JSON
+2. For each test case:
+   - Compute buckets and verify against `expectedHashing`
+   - Resolve parameters and verify against `expectedAssignments`
+
+## Hash Function Reference
+
+Traffical uses **FNV-1a (32-bit)** for bucket computation:
+
+```
+Input: unitKeyValue + ":" + layerId
+Hash: FNV-1a(input) >>> 0
+Bucket: hash % bucketCount
+```
+
+### Example
+
+- Input: `"user-abc:layer_ui"`
+- FNV-1a hash: `2947556742`
+- Bucket (mod 1000): `742`
+
+### FNV-1a Algorithm
+
+```
+FNV_OFFSET_BASIS = 2166136261
+FNV_PRIME = 16777619
+
+hash = FNV_OFFSET_BASIS
+for each byte in input:
+    hash = hash XOR byte
+    hash = hash * FNV_PRIME
+return hash >>> 0  // Ensure unsigned 32-bit
+```
+
+## SDK Implementations
+
+| Language | Repository |
+|----------|------------|
+| JavaScript/TypeScript | [traffical/js-sdk](https://github.com/traffical/js-sdk) |
+| Go | Coming soon |
+| Java | Coming soon |
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

package/index.cjs

@@ -0,0 +1,37 @@
+/**
+ * @traffical/sdk-spec (CommonJS)
+ * 
+ * Language-agnostic specifications for Traffical SDKs.
+ * Provides JSON schemas and test vectors for validation.
+ */
+
+const path = require('path');
+
+// Schemas
+exports.configBundleSchema = require('./schemas/config-bundle.schema.json');
+exports.eventsSchema = require('./schemas/events.schema.json');
+exports.trafficalConfigSchema = require('./schemas/traffical-config.schema.json');
+
+// Test vector bundles
+exports.bundleBasic = require('./test-vectors/fixtures/bundle_basic.json');
+exports.bundleConditions = require('./test-vectors/fixtures/bundle_conditions.json');
+
+// Test vector expected results
+exports.expectedBasic = require('./test-vectors/fixtures/expected_basic.json');
+exports.expectedConditions = require('./test-vectors/fixtures/expected_conditions.json');
+
+// Schema paths (for tools that need file paths)
+exports.schemaPaths = {
+  configBundle: path.join(__dirname, 'schemas/config-bundle.schema.json'),
+  events: path.join(__dirname, 'schemas/events.schema.json'),
+  trafficalConfig: path.join(__dirname, 'schemas/traffical-config.schema.json'),
+};
+
+// Test vector paths
+exports.testVectorPaths = {
+  bundleBasic: path.join(__dirname, 'test-vectors/fixtures/bundle_basic.json'),
+  bundleConditions: path.join(__dirname, 'test-vectors/fixtures/bundle_conditions.json'),
+  expectedBasic: path.join(__dirname, 'test-vectors/fixtures/expected_basic.json'),
+  expectedConditions: path.join(__dirname, 'test-vectors/fixtures/expected_conditions.json'),
+};
+

package/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @traffical/sdk-spec
+ * 
+ * Type definitions for Traffical SDK specifications.
+ */
+
+import type { JSONSchema7 } from 'json-schema';
+
+// Schema types
+export declare const configBundleSchema: JSONSchema7;
+export declare const eventsSchema: JSONSchema7;
+export declare const trafficalConfigSchema: JSONSchema7;
+
+// Test vector bundle types
+export interface TestBundle {
+  orgId: string;
+  projectId: string;
+  env: string;
+  version: number;
+  hashing: {
+    unitKey: string;
+    bucketCount: number;
+  };
+  parameters: Record<string, {
+    type: string;
+    default: unknown;
+    layers?: string[];
+  }>;
+  layers: Array<{
+    id: string;
+    priority: number;
+    policies: Array<{
+      id: string;
+      parameters: Record<string, unknown>;
+      allocations: Array<{
+        name: string;
+        bucketRange: [number, number];
+        parameters: Record<string, unknown>;
+      }>;
+      conditions?: Array<{
+        type: string;
+        field: string;
+        operator: string;
+        value: unknown;
+      }>;
+    }>;
+  }>;
+}
+
+export interface ExpectedResults {
+  description: string;
+  testCases: Array<{
+    name: string;
+    context: Record<string, unknown>;
+    expectedHashing?: Record<string, {
+      input: string;
+      bucket: number;
+    }>;
+    expectedAssignments: Record<string, unknown>;
+  }>;
+}
+
+export declare const bundleBasic: TestBundle;
+export declare const bundleConditions: TestBundle;
+export declare const expectedBasic: ExpectedResults;
+export declare const expectedConditions: ExpectedResults;
+
+// Path exports
+export declare const schemaPaths: {
+  configBundle: string;
+  events: string;
+  trafficalConfig: string;
+};
+
+export declare const testVectorPaths: {
+  bundleBasic: string;
+  bundleConditions: string;
+  expectedBasic: string;
+  expectedConditions: string;
+};
+

package/index.js

@@ -0,0 +1,38 @@
+/**
+ * @traffical/sdk-spec
+ * 
+ * Language-agnostic specifications for Traffical SDKs.
+ * Provides JSON schemas and test vectors for validation.
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+// Schemas
+export const configBundleSchema = require('./schemas/config-bundle.schema.json');
+export const eventsSchema = require('./schemas/events.schema.json');
+export const trafficalConfigSchema = require('./schemas/traffical-config.schema.json');
+
+// Test vector bundles
+export const bundleBasic = require('./test-vectors/fixtures/bundle_basic.json');
+export const bundleConditions = require('./test-vectors/fixtures/bundle_conditions.json');
+
+// Test vector expected results
+export const expectedBasic = require('./test-vectors/fixtures/expected_basic.json');
+export const expectedConditions = require('./test-vectors/fixtures/expected_conditions.json');
+
+// Schema paths (for tools that need file paths)
+export const schemaPaths = {
+  configBundle: new URL('./schemas/config-bundle.schema.json', import.meta.url).pathname,
+  events: new URL('./schemas/events.schema.json', import.meta.url).pathname,
+  trafficalConfig: new URL('./schemas/traffical-config.schema.json', import.meta.url).pathname,
+};
+
+// Test vector paths
+export const testVectorPaths = {
+  bundleBasic: new URL('./test-vectors/fixtures/bundle_basic.json', import.meta.url).pathname,
+  bundleConditions: new URL('./test-vectors/fixtures/bundle_conditions.json', import.meta.url).pathname,
+  expectedBasic: new URL('./test-vectors/fixtures/expected_basic.json', import.meta.url).pathname,
+  expectedConditions: new URL('./test-vectors/fixtures/expected_conditions.json', import.meta.url).pathname,
+};
+

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@traffical/sdk-spec",
+  "version": "0.1.0",
+  "description": "Language-agnostic specifications for Traffical SDKs - schemas and test vectors",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    },
+    "./schemas/*": "./schemas/*",
+    "./test-vectors/*": "./test-vectors/*"
+  },
+  "files": [
+    "schemas",
+    "test-vectors",
+    "index.js",
+    "index.cjs",
+    "index.d.ts"
+  ],
+  "scripts": {},
+  "keywords": [
+    "traffical",
+    "sdk",
+    "specification",
+    "schema",
+    "test-vectors",
+    "feature-flags",
+    "experimentation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/traffical/sdk-spec"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/schemas/config-bundle.schema.json

@@ -0,0 +1,208 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://traffical.io/schemas/config-bundle.json",
+  "title": "ConfigBundle",
+  "description": "The complete configuration bundle for a Traffical project/environment. This is what the SDK fetches and caches.",
+  "type": "object",
+  "required": ["version", "orgId", "projectId", "env", "hashing", "parameters", "layers"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO timestamp for cache invalidation / ETag generation"
+    },
+    "orgId": {
+      "type": "string",
+      "description": "Organization ID"
+    },
+    "projectId": {
+      "type": "string",
+      "description": "Project ID"
+    },
+    "env": {
+      "type": "string",
+      "description": "Environment (e.g., 'production', 'staging')"
+    },
+    "hashing": {
+      "$ref": "#/definitions/BundleHashingConfig"
+    },
+    "parameters": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/BundleParameter"
+      },
+      "description": "All parameters for this project/env with defaults and layer membership"
+    },
+    "layers": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/BundleLayer"
+      },
+      "description": "All layers with their policies"
+    }
+  },
+  "definitions": {
+    "BundleHashingConfig": {
+      "type": "object",
+      "required": ["unitKey", "bucketCount"],
+      "properties": {
+        "unitKey": {
+          "type": "string",
+          "description": "The context field name to use as the unit key (e.g., 'userId', 'deviceId')"
+        },
+        "bucketCount": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Total number of buckets for allocation (e.g., 1000, 10000)"
+        }
+      }
+    },
+    "BundleParameter": {
+      "type": "object",
+      "required": ["key", "type", "default", "layerId", "namespace"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Parameter key (e.g., 'ui.primaryColor', 'pricing.discount')"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "json"],
+          "description": "Value type"
+        },
+        "default": {
+          "description": "Default value when no policy overrides apply"
+        },
+        "layerId": {
+          "type": "string",
+          "description": "The layer this parameter belongs to"
+        },
+        "namespace": {
+          "type": "string",
+          "description": "Namespace for organizational purposes"
+        }
+      }
+    },
+    "BundleLayer": {
+      "type": "object",
+      "required": ["id", "policies"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Layer ID"
+        },
+        "policies": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/BundlePolicy"
+          },
+          "description": "Policies within this layer (evaluated in order)"
+        }
+      }
+    },
+    "BundleContextLogging": {
+      "type": "object",
+      "required": ["allowedFields"],
+      "properties": {
+        "allowedFields": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Context fields to include in exposure events (allowlist). Only these fields will be logged for contextual bandit training."
+        }
+      },
+      "description": "Configuration for context logging in exposure events. Used for contextual bandit training while protecting PII."
+    },
+    "BundlePolicy": {
+      "type": "object",
+      "required": ["id", "state", "kind", "allocations", "conditions"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Policy ID for tracking and analytics"
+        },
+        "state": {
+          "type": "string",
+          "enum": ["draft", "running", "paused", "completed"],
+          "description": "Current state of the policy"
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["static", "adaptive"],
+          "description": "Policy kind: 'static' for fixed allocations, 'adaptive' for learning-based"
+        },
+        "allocations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/BundleAllocation"
+          },
+          "description": "Bucket ranges mapped to parameter overrides"
+        },
+        "conditions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/BundleCondition"
+          },
+          "description": "Context predicates that must all match for eligibility"
+        },
+        "stateVersion": {
+          "type": "string",
+          "format": "date-time",
+          "description": "For adaptive policies: version of the optimization state"
+        },
+        "contextLogging": {
+          "$ref": "#/definitions/BundleContextLogging",
+          "description": "For adaptive policies: context fields to log in exposure events for contextual bandit training"
+        }
+      }
+    },
+    "BundleAllocation": {
+      "type": "object",
+      "required": ["name", "bucketRange", "overrides"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Variant name for tracking (e.g., 'control', 'treatment_a')"
+        },
+        "bucketRange": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "Bucket range [start, end] inclusive"
+        },
+        "overrides": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Parameter overrides for units in this bucket range"
+        }
+      }
+    },
+    "BundleCondition": {
+      "type": "object",
+      "required": ["field", "op"],
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Context field to evaluate"
+        },
+        "op": {
+          "type": "string",
+          "enum": ["eq", "neq", "in", "nin", "gt", "gte", "lt", "lte", "contains", "startsWith", "endsWith", "regex", "exists", "notExists"],
+          "description": "Comparison operator"
+        },
+        "value": {
+          "description": "Single value for binary operators"
+        },
+        "values": {
+          "type": "array",
+          "description": "Multiple values for 'in'/'nin' operators"
+        }
+      }
+    }
+  }
+}
+

package/schemas/events.schema.json

@@ -0,0 +1,239 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://traffical.io/schemas/events.json",
+  "title": "TrafficalEvents",
+  "description": "Event schemas for tracking exposures, decisions, and user events in Traffical",
+  "definitions": {
+    "BaseEvent": {
+      "type": "object",
+      "required": ["type", "orgId", "projectId", "env", "unitKey", "timestamp"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Optional client-generated event ID for deduplication and linking"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["exposure", "decision", "track"],
+          "description": "Event type"
+        },
+        "orgId": {
+          "type": "string",
+          "description": "Organization ID"
+        },
+        "projectId": {
+          "type": "string",
+          "description": "Project ID"
+        },
+        "env": {
+          "type": "string",
+          "description": "Environment"
+        },
+        "unitKey": {
+          "type": "string",
+          "description": "Unit key value - the identifier used for bucketing"
+        },
+        "userId": {
+          "type": "string",
+          "description": "Optional user identifier"
+        },
+        "anonymousId": {
+          "type": "string",
+          "description": "Optional anonymous identifier"
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "Optional session identifier"
+        },
+        "requestId": {
+          "type": "string",
+          "description": "Optional request identifier"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Event timestamp (ISO 8601)"
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Context snapshot at the time of the event"
+        },
+        "sdkName": {
+          "type": "string",
+          "description": "SDK that generated this event (e.g., 'js-client', 'node', 'react')"
+        },
+        "sdkVersion": {
+          "type": "string",
+          "description": "Version of the SDK that generated this event"
+        }
+      }
+    },
+    "ExposureLayerInfo": {
+      "type": "object",
+      "required": ["layerId", "bucket"],
+      "properties": {
+        "layerId": {
+          "type": "string"
+        },
+        "bucket": {
+          "type": "integer"
+        },
+        "policyId": {
+          "type": "string"
+        },
+        "allocationName": {
+          "type": "string"
+        }
+      }
+    },
+    "TrackAttribution": {
+      "type": "object",
+      "required": ["layerId", "policyId", "allocationName"],
+      "properties": {
+        "layerId": {
+          "type": "string"
+        },
+        "policyId": {
+          "type": "string"
+        },
+        "allocationName": {
+          "type": "string"
+        },
+        "weight": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Attribution weight (0.0-1.0)"
+        },
+        "model": {
+          "type": "string",
+          "enum": ["first_touch", "last_touch", "linear", "time_decay", "position_based"],
+          "description": "Attribution model used"
+        }
+      }
+    },
+    "ExposureEvent": {
+      "allOf": [
+        { "$ref": "#/definitions/BaseEvent" },
+        {
+          "type": "object",
+          "required": ["assignments", "layers"],
+          "properties": {
+            "type": {
+              "const": "exposure"
+            },
+            "assignments": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "The parameter assignments that were exposed"
+            },
+            "layers": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/ExposureLayerInfo"
+              },
+              "description": "Per-layer resolution metadata"
+            },
+            "decisionId": {
+              "type": "string",
+              "description": "Reference to the decision event"
+            }
+          }
+        }
+      ]
+    },
+    "DecisionEvent": {
+      "allOf": [
+        { "$ref": "#/definitions/BaseEvent" },
+        {
+          "type": "object",
+          "required": ["assignments", "layers"],
+          "properties": {
+            "type": {
+              "const": "decision"
+            },
+            "requestedParameters": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Parameters that were requested"
+            },
+            "assignments": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "The resolved assignments"
+            },
+            "layers": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/ExposureLayerInfo"
+              },
+              "description": "Resolution metadata"
+            },
+            "latencyMs": {
+              "type": "integer",
+              "description": "Processing time in milliseconds"
+            }
+          }
+        }
+      ]
+    },
+    "TrackEvent": {
+      "allOf": [
+        { "$ref": "#/definitions/BaseEvent" },
+        {
+          "type": "object",
+          "required": ["event"],
+          "properties": {
+            "type": {
+              "const": "track"
+            },
+            "event": {
+              "type": "string",
+              "description": "Event name (e.g., 'purchase', 'add_to_cart', 'page_view')"
+            },
+            "decisionId": {
+              "type": "string",
+              "description": "Reference to the decision event for attribution"
+            },
+            "value": {
+              "type": "number",
+              "description": "Primary numeric value for optimization (e.g., revenue amount)"
+            },
+            "values": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "number"
+              },
+              "description": "Secondary values for multi-objective optimization"
+            },
+            "properties": {
+              "type": "object",
+              "additionalProperties": true,
+              "description": "Event properties/metadata (e.g., orderId, itemSku)"
+            },
+            "attribution": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/TrackAttribution"
+              },
+              "description": "Attribution chain - which policies/allocations influenced this"
+            },
+            "eventTimestamp": {
+              "type": "string",
+              "format": "date-time",
+              "description": "For delayed events: the original event timestamp"
+            }
+          }
+        }
+      ]
+    }
+  },
+  "oneOf": [
+    { "$ref": "#/definitions/ExposureEvent" },
+    { "$ref": "#/definitions/DecisionEvent" },
+    { "$ref": "#/definitions/TrackEvent" }
+  ]
+}

package/schemas/traffical-config.schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://traffical.io/schemas/config.json",
+  "title": "TrafficalConfig",
+  "description": "Traffical configuration file schema for traffical.yaml",
+  "type": "object",
+  "required": ["version", "project", "parameters"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["1.0"],
+      "description": "Config file version"
+    },
+    "project": {
+      "type": "object",
+      "description": "Project identification",
+      "required": ["id", "orgId"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^proj_",
+          "description": "Project ID from Traffical (starts with proj_)"
+        },
+        "orgId": {
+          "type": "string",
+          "pattern": "^org_",
+          "description": "Organization ID from Traffical (starts with org_)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "parameters": {
+      "type": "object",
+      "description": "Parameters synced from this config file",
+      "additionalProperties": {
+        "$ref": "#/definitions/parameter"
+      }
+    },
+    "events": {
+      "type": "object",
+      "description": "Event definitions synced from this config file",
+      "additionalProperties": {
+        "$ref": "#/definitions/event"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "parameter": {
+      "type": "object",
+      "description": "Parameter definition",
+      "required": ["type", "default"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["string", "number", "boolean", "json"],
+          "description": "The type of value this parameter holds"
+        },
+        "default": {
+          "description": "Default value used when no policy overrides apply"
+        },
+        "namespace": {
+          "type": "string",
+          "description": "Organizational grouping for the parameter"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the parameter"
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "string" } }
+          },
+          "then": {
+            "properties": { "default": { "type": "string" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "number" } }
+          },
+          "then": {
+            "properties": { "default": { "type": "number" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "boolean" } }
+          },
+          "then": {
+            "properties": { "default": { "type": "boolean" } }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "json" } }
+          },
+          "then": {
+            "properties": {
+              "default": {
+                "oneOf": [
+                  { "type": "object" },
+                  { "type": "array" }
+                ]
+              }
+            }
+          }
+        }
+      ]
+    },
+    "event": {
+      "type": "object",
+      "description": "Event definition",
+      "required": ["valueType"],
+      "properties": {
+        "valueType": {
+          "type": "string",
+          "enum": ["currency", "count", "rate", "boolean"],
+          "description": "The type of value this event tracks"
+        },
+        "unit": {
+          "type": "string",
+          "description": "Optional unit for the value (e.g., 'USD', 'items', 'percent')"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the event"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "version": "1.0",
+      "project": {
+        "id": "proj_abc123",
+        "orgId": "org_xyz789"
+      },
+      "parameters": {
+        "checkout.button.color": {
+          "type": "string",
+          "default": "#FF6600",
+          "namespace": "checkout",
+          "description": "Primary CTA button background color"
+        },
+        "checkout.new_flow.enabled": {
+          "type": "boolean",
+          "default": false,
+          "namespace": "checkout"
+        },
+        "pricing.discount.percentage": {
+          "type": "number",
+          "default": 0,
+          "namespace": "pricing"
+        },
+        "ui.theme.config": {
+          "type": "json",
+          "default": {
+            "primaryColor": "#FF6600",
+            "borderRadius": 8
+          },
+          "namespace": "ui"
+        }
+      },
+      "events": {
+        "purchase": {
+          "valueType": "currency",
+          "unit": "USD",
+          "description": "User completes a purchase"
+        },
+        "add_to_cart": {
+          "valueType": "count",
+          "description": "User adds item to cart"
+        },
+        "checkout_started": {
+          "valueType": "boolean",
+          "description": "User initiates checkout"
+        }
+      }
+    }
+  ]
+}
+

package/test-vectors/README.md

@@ -0,0 +1,77 @@
+# Traffical SDK Test Vectors
+
+This directory contains deterministic test fixtures for validating SDK implementations across languages.
+
+## Purpose
+
+All Traffical SDKs must produce identical results for the same inputs. These test vectors ensure:
+
+1. **Hashing consistency** - FNV-1a hash produces the same bucket across all implementations
+2. **Resolution correctness** - Parameter resolution follows the layered priority system
+3. **Condition evaluation** - Context predicates are evaluated identically
+
+## Fixture Structure
+
+```
+fixtures/
+├── bundle_*.json        # Config bundles to test against
+└── expected_*.json      # Expected outputs for each bundle
+```
+
+### Bundle Files
+
+Each bundle file contains a complete `ConfigBundle` with:
+- Hashing configuration
+- Parameters with defaults
+- Layers with policies and allocations
+
+### Expected Output Files
+
+Each expected file contains:
+- Reference to the bundle file
+- Array of test cases with:
+  - Input context
+  - Expected bucket assignments (for hashing validation)
+  - Expected parameter assignments
+
+## Running Tests
+
+### TypeScript (Reference Implementation)
+
+```bash
+cd sdk/core-ts
+bun test
+```
+
+### Other Languages
+
+Each SDK implementation should:
+
+1. Load the bundle JSON
+2. For each test case:
+   - Compute buckets and verify against `expectedHashing`
+   - Resolve parameters and verify against `expectedAssignments`
+
+## Adding New Test Cases
+
+When adding new test vectors:
+
+1. Create or update a bundle file with the configuration to test
+2. Use the TypeScript SDK to compute expected outputs
+3. Add test cases with clear comments explaining the expected behavior
+
+## Hash Function Reference
+
+Traffical uses FNV-1a (32-bit) for bucket computation:
+
+```
+Input: unitKeyValue + ":" + layerId
+Hash: FNV-1a(input) >>> 0
+Bucket: hash % bucketCount
+```
+
+Example:
+- Input: `"user-abc:layer_ui"`
+- FNV-1a hash: `2947556742`
+- Bucket (mod 1000): `742`
+

package/test-vectors/fixtures/bundle_basic.json

@@ -0,0 +1,89 @@
+{
+  "version": "2024-01-01T00:00:00.000Z",
+  "orgId": "org_test",
+  "projectId": "proj_test",
+  "env": "production",
+  "hashing": {
+    "unitKey": "userId",
+    "bucketCount": 1000
+  },
+  "parameters": [
+    {
+      "key": "ui.primaryColor",
+      "type": "string",
+      "default": "#000000",
+      "layerId": "layer_ui",
+      "namespace": "ui"
+    },
+    {
+      "key": "ui.buttonText",
+      "type": "string",
+      "default": "Click Me",
+      "layerId": "layer_ui",
+      "namespace": "ui"
+    },
+    {
+      "key": "pricing.discount",
+      "type": "number",
+      "default": 0,
+      "layerId": "layer_pricing",
+      "namespace": "pricing"
+    }
+  ],
+  "layers": [
+    {
+      "id": "layer_ui",
+      "policies": [
+        {
+          "id": "policy_color_test",
+          "state": "running",
+          "kind": "static",
+          "allocations": [
+            {
+              "name": "control",
+              "bucketRange": [0, 499],
+              "overrides": {
+                "ui.primaryColor": "#0000FF"
+              }
+            },
+            {
+              "name": "treatment",
+              "bucketRange": [500, 999],
+              "overrides": {
+                "ui.primaryColor": "#FF0000"
+              }
+            }
+          ],
+          "conditions": []
+        }
+      ]
+    },
+    {
+      "id": "layer_pricing",
+      "policies": [
+        {
+          "id": "policy_discount",
+          "state": "running",
+          "kind": "static",
+          "allocations": [
+            {
+              "name": "discount_10",
+              "bucketRange": [0, 299],
+              "overrides": {
+                "pricing.discount": 10
+              }
+            },
+            {
+              "name": "discount_20",
+              "bucketRange": [300, 599],
+              "overrides": {
+                "pricing.discount": 20
+              }
+            }
+          ],
+          "conditions": []
+        }
+      ]
+    }
+  ]
+}

package/test-vectors/fixtures/bundle_conditions.json

@@ -0,0 +1,76 @@
+{
+  "version": "2024-01-01T00:00:00.000Z",
+  "orgId": "org_test",
+  "projectId": "proj_test",
+  "env": "production",
+  "hashing": {
+    "unitKey": "userId",
+    "bucketCount": 1000
+  },
+  "parameters": [
+    {
+      "key": "checkout.ctaText",
+      "type": "string",
+      "default": "Complete Purchase",
+      "layerId": "layer_checkout",
+      "namespace": "checkout"
+    },
+    {
+      "key": "checkout.showUrgency",
+      "type": "boolean",
+      "default": false,
+      "layerId": "layer_checkout",
+      "namespace": "checkout"
+    }
+  ],
+  "layers": [
+    {
+      "id": "layer_checkout",
+      "policies": [
+        {
+          "id": "policy_high_value",
+          "state": "running",
+          "kind": "static",
+          "allocations": [
+            {
+              "name": "urgency_treatment",
+              "bucketRange": [0, 999],
+              "overrides": {
+                "checkout.ctaText": "Buy Now - Limited Stock!",
+                "checkout.showUrgency": true
+              }
+            }
+          ],
+          "conditions": [
+            {
+              "field": "cartValue",
+              "op": "gte",
+              "value": 100
+            }
+          ]
+        },
+        {
+          "id": "policy_mobile",
+          "state": "running",
+          "kind": "static",
+          "allocations": [
+            {
+              "name": "mobile_cta",
+              "bucketRange": [0, 999],
+              "overrides": {
+                "checkout.ctaText": "Buy Now"
+              }
+            }
+          ],
+          "conditions": [
+            {
+              "field": "deviceType",
+              "op": "eq",
+              "value": "mobile"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/test-vectors/fixtures/expected_basic.json

@@ -0,0 +1,72 @@
+{
+  "description": "Test vectors for basic parameter resolution",
+  "bundle": "bundle_basic.json",
+  "testCases": [
+    {
+      "name": "user_abc_treatment_group",
+      "context": {
+        "userId": "user-abc"
+      },
+      "expectedHashing": {
+        "layer_ui": {
+          "bucket": 551,
+          "comment": "FNV-1a hash of 'user-abc:layer_ui' mod 1000"
+        },
+        "layer_pricing": {
+          "bucket": 913,
+          "comment": "FNV-1a hash of 'user-abc:layer_pricing' mod 1000"
+        }
+      },
+      "expectedAssignments": {
+        "ui.primaryColor": "#FF0000",
+        "ui.buttonText": "Click Me",
+        "pricing.discount": 0
+      },
+      "comment": "User in treatment bucket for UI (551 >= 500), no discount (913 >= 600)"
+    },
+    {
+      "name": "user_xyz_control_group",
+      "context": {
+        "userId": "user-xyz"
+      },
+      "expectedHashing": {
+        "layer_ui": {
+          "bucket": 214,
+          "comment": "FNV-1a hash of 'user-xyz:layer_ui' mod 1000"
+        },
+        "layer_pricing": {
+          "bucket": 42,
+          "comment": "FNV-1a hash of 'user-xyz:layer_pricing' mod 1000"
+        }
+      },
+      "expectedAssignments": {
+        "ui.primaryColor": "#0000FF",
+        "ui.buttonText": "Click Me",
+        "pricing.discount": 10
+      },
+      "comment": "User in control bucket for UI (214 < 500), 10% discount (42 in 0-299)"
+    },
+    {
+      "name": "user_123_treatment",
+      "context": {
+        "userId": "user-123"
+      },
+      "expectedHashing": {
+        "layer_ui": {
+          "bucket": 871,
+          "comment": "FNV-1a hash of 'user-123:layer_ui' mod 1000"
+        },
+        "layer_pricing": {
+          "bucket": 177,
+          "comment": "FNV-1a hash of 'user-123:layer_pricing' mod 1000"
+        }
+      },
+      "expectedAssignments": {
+        "ui.primaryColor": "#FF0000",
+        "ui.buttonText": "Click Me",
+        "pricing.discount": 10
+      },
+      "comment": "User in treatment bucket for UI (871 >= 500), 10% discount (177 in 0-299)"
+    }
+  ]
+}

package/test-vectors/fixtures/expected_conditions.json

@@ -0,0 +1,59 @@
+{
+  "description": "Test vectors for condition-based targeting",
+  "bundle": "bundle_conditions.json",
+  "testCases": [
+    {
+      "name": "high_value_cart",
+      "context": {
+        "userId": "user-high-value",
+        "cartValue": 150,
+        "deviceType": "desktop"
+      },
+      "expectedAssignments": {
+        "checkout.ctaText": "Buy Now - Limited Stock!",
+        "checkout.showUrgency": true
+      },
+      "comment": "High value cart triggers urgency treatment"
+    },
+    {
+      "name": "mobile_user_low_cart",
+      "context": {
+        "userId": "user-mobile",
+        "cartValue": 50,
+        "deviceType": "mobile"
+      },
+      "expectedAssignments": {
+        "checkout.ctaText": "Buy Now",
+        "checkout.showUrgency": false
+      },
+      "comment": "Mobile user with low cart value gets mobile CTA"
+    },
+    {
+      "name": "desktop_user_low_cart",
+      "context": {
+        "userId": "user-desktop",
+        "cartValue": 50,
+        "deviceType": "desktop"
+      },
+      "expectedAssignments": {
+        "checkout.ctaText": "Complete Purchase",
+        "checkout.showUrgency": false
+      },
+      "comment": "Desktop user with low cart value gets defaults"
+    },
+    {
+      "name": "mobile_user_high_cart",
+      "context": {
+        "userId": "user-mobile-high",
+        "cartValue": 200,
+        "deviceType": "mobile"
+      },
+      "expectedAssignments": {
+        "checkout.ctaText": "Buy Now - Limited Stock!",
+        "checkout.showUrgency": true
+      },
+      "comment": "High value cart condition takes precedence (first matching policy)"
+    }
+  ]
+}
+