@caelo-cms/edge-router 0.10.23

package/README.md

@@ -0,0 +1,25 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+
+# @caelo-cms/edge-router
+
+Locale-aware edge request router for [Caelo CMS](https://github.com/caelo-cms/caelo-cms)
+deployments. Maps incoming visitor URLs onto the static site's locale/URL
+strategy (prefix, domain, or hybrid) from the deploy manifest — the same
+routing logic everywhere a request first lands:
+
+- the provisioning stacks' edge handlers bundle it at provision time
+  (Lambda@Edge on AWS; the equivalent edge hooks on the GCP and Azure
+  stacks),
+- the static generator uses it to precompute per-locale routes.
+
+It is published as part of Caelo's lockstep release because the shipped
+`@caelo-cms/provisioning` package depends on it at provision time. It has no
+runtime dependencies.
+
+You normally don't install this directly — it comes in through
+`bunx @caelo-cms/provisioning`. See the
+[main repository](https://github.com/caelo-cms/caelo-cms) for documentation.
+
+## License
+
+MPL-2.0

package/dist/assignment.d.ts

@@ -0,0 +1,70 @@
+/**
+ * P15 — stable-hash A/B variant assignment.
+ *
+ * MUST produce byte-identical results across all four runtimes:
+ *   - self-hosted (P13 Caddy gateway)
+ *   - GCP edge router (Cloud Run header rule)
+ *   - AWS edge router (Lambda@Edge)
+ *   - Azure edge router (Front Door rules engine)
+ *
+ * Drift between runtimes means a visitor sees different variants
+ * depending on which provider serves them — silent A/B contamination.
+ * The byte-identity test in `index.test.ts` asserts a fixed corpus of
+ * (visitorId, manifestVersion, experimentId) tuples maps to the same
+ * variant label on every implementation.
+ *
+ * Algorithm: FNV-1a 32-bit hash of (visitorId + ":" + experimentId +
+ * ":" + manifestVersion). The 32-bit space mod 100 gives a bucket in
+ * [0, 99]; cumulative variant weights determine the variant. Pure +
+ * deterministic; no randomness, no time, no provider-specific code.
+ */
+import type { ManifestExperiment, ManifestVariant } from "./manifest.js";
+/**
+ * FNV-1a 32-bit. Standard offset basis 0x811c9dc5, prime 0x01000193.
+ * Implemented in plain TypeScript so every runtime (V8 / SpiderMonkey
+ * / Node L@E sandbox / Bun) produces byte-identical output.
+ */
+export declare function fnv1a32(input: string): number;
+/**
+ * Assign a variant to a visitor for one experiment. Inputs:
+ *   - visitorId: stable opaque string from the `caelo_visitor_id` cookie.
+ *   - manifestVersion: bumped per deploy so a re-bucketing rolls out
+ *     atomically (operators occasionally need to re-randomize after a
+ *     biased early sample).
+ *   - experiment: the matched ManifestExperiment.
+ *
+ * Returns the chosen variant + its rewrite path. Pure; no I/O.
+ */
+export declare function assignVariant(opts: {
+    readonly visitorId: string;
+    readonly manifestVersion: string;
+    readonly experiment: ManifestExperiment;
+}): ManifestVariant;
+/**
+ * Format the assignment-log entry every runtime emits. Same JSON shape
+ * across providers so the P12A analytics plugin's per-provider log
+ * adapters can normalise into one `ab_assignment_aggregates` query.
+ */
+export interface AssignmentLogEntry {
+    readonly kind: "ab_assignment";
+    readonly experimentId: string;
+    readonly variantLabel: string;
+    readonly visitorId: string;
+    readonly manifestVersion: string;
+    readonly tsMs: number;
+}
+export declare function buildAssignmentLog(opts: {
+    readonly experimentId: string;
+    readonly variant: ManifestVariant;
+    readonly visitorId: string;
+    readonly manifestVersion: string;
+    readonly nowMs?: number;
+}): AssignmentLogEntry;
+/**
+ * Mint a stable opaque visitor id when the request didn't carry the
+ * `caelo_visitor_id` cookie. Format: 16 hex bytes (128 bits — collision
+ * resistant for any plausible visitor population). Edge routers set
+ * this on the response cookie so the next request inherits the same id.
+ */
+export declare function mintVisitorId(): string;
+//# sourceMappingURL=assignment.d.ts.map

package/dist/assignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment.d.ts","sourceRoot":"","sources":["../src/assignment.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU7C;AAcD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;CACzC,GAAG,eAAe,CAclB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,kBAAkB,CASrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAMtC"}

package/dist/assignment.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * FNV-1a 32-bit. Standard offset basis 0x811c9dc5, prime 0x01000193.
+ * Implemented in plain TypeScript so every runtime (V8 / SpiderMonkey
+ * / Node L@E sandbox / Bun) produces byte-identical output.
+ */
+export function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        // Multiply by FNV prime, keeping in 32-bit unsigned range. Math.imul
+        // is the cross-runtime way to do 32-bit-truncated integer multiply.
+        hash = Math.imul(hash, 0x01000193);
+    }
+    // Coerce back to unsigned 32-bit.
+    return hash >>> 0;
+}
+/**
+ * Compute the cumulative bucket boundaries for an experiment's variants.
+ * Stable: same input order → same boundaries → same assignment.
+ */
+function bucketBoundaries(variants) {
+    let cum = 0;
+    return variants.map((v) => {
+        cum += v.weight;
+        return cum;
+    });
+}
+/**
+ * Assign a variant to a visitor for one experiment. Inputs:
+ *   - visitorId: stable opaque string from the `caelo_visitor_id` cookie.
+ *   - manifestVersion: bumped per deploy so a re-bucketing rolls out
+ *     atomically (operators occasionally need to re-randomize after a
+ *     biased early sample).
+ *   - experiment: the matched ManifestExperiment.
+ *
+ * Returns the chosen variant + its rewrite path. Pure; no I/O.
+ */
+export function assignVariant(opts) {
+    const key = `${opts.visitorId}:${opts.experiment.experimentId}:${opts.manifestVersion}`;
+    const hash = fnv1a32(key);
+    const bucket = hash % 100;
+    const boundaries = bucketBoundaries(opts.experiment.variants);
+    for (let i = 0; i < boundaries.length; i += 1) {
+        if (bucket < (boundaries[i] ?? 0)) {
+            const v = opts.experiment.variants[i];
+            if (v)
+                return v;
+        }
+    }
+    // Fallthrough (weights summed to 100 but float drift) — return last.
+    // Schema-level validation guarantees this doesn't happen in practice.
+    return opts.experiment.variants[opts.experiment.variants.length - 1];
+}
+export function buildAssignmentLog(opts) {
+    return {
+        kind: "ab_assignment",
+        experimentId: opts.experimentId,
+        variantLabel: opts.variant.label,
+        visitorId: opts.visitorId,
+        manifestVersion: opts.manifestVersion,
+        tsMs: opts.nowMs ?? Date.now(),
+    };
+}
+/**
+ * Mint a stable opaque visitor id when the request didn't carry the
+ * `caelo_visitor_id` cookie. Format: 16 hex bytes (128 bits — collision
+ * resistant for any plausible visitor population). Edge routers set
+ * this on the response cookie so the next request inherits the same id.
+ */
+export function mintVisitorId() {
+    const buf = new Uint8Array(16);
+    // crypto.getRandomValues is available in V8 / Node / L@E / Bun /
+    // every modern runtime; no Node Buffer fallback needed.
+    crypto.getRandomValues(buf);
+    return [...buf].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=assignment.js.map

package/dist/assignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assignment.js","sourceRoot":"","sources":["../src/assignment.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAyBnC;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,qEAAqE;QACrE,oEAAoE;QACpE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,kCAAkC;IAClC,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,QAAwC;IAChE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACxB,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC;QAChB,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,IAI7B;IACC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;IACxF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,IAAI,GAAG,GAAG,CAAC;IAC1B,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,IAAI,MAAM,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YACtC,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,qEAAqE;IACrE,sEAAsE;IACtE,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAoB,CAAC;AAC1F,CAAC;AAgBD,MAAM,UAAU,kBAAkB,CAAC,IAMlC;IACC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;QAChC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,IAAI,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IAC/B,iEAAiE;IACjE,wDAAwD;IACxD,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACvE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @caelo-cms/edge-router — P15.
+ *
+ * Provider-agnostic edge-routing logic for A/B experiments. The same
+ * hash → same variant → same rewrite path holds across self-hosted
+ * (P13 Caddy gateway) + GCP + AWS + Azure. Provider-specific shims
+ * land in `packages/provisioning/stacks/<provider>/edge-handler.ts`
+ * and import this package's `routeRequest` for the actual decision.
+ */
+export { type AssignmentLogEntry, assignVariant, buildAssignmentLog, fnv1a32, mintVisitorId, } from "./assignment.js";
+export { EMPTY_MANIFEST, findExperimentForUrl, type ManifestExperiment, type ManifestVariant, type RoutingManifest, validateManifest, } from "./manifest.js";
+export { type EdgeRequestSummary, type EdgeRouteDecision, routeRequest } from "./router.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,aAAa,EACb,kBAAkB,EAClB,OAAO,EACP,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * @caelo-cms/edge-router — P15.
+ *
+ * Provider-agnostic edge-routing logic for A/B experiments. The same
+ * hash → same variant → same rewrite path holds across self-hosted
+ * (P13 Caddy gateway) + GCP + AWS + Azure. Provider-specific shims
+ * land in `packages/provisioning/stacks/<provider>/edge-handler.ts`
+ * and import this package's `routeRequest` for the actual decision.
+ */
+export { assignVariant, buildAssignmentLog, fnv1a32, mintVisitorId, } from "./assignment.js";
+export { EMPTY_MANIFEST, findExperimentForUrl, validateManifest, } from "./manifest.js";
+export { routeRequest } from "./router.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;GAQG;AAEH,OAAO,EAEL,aAAa,EACb,kBAAkB,EAClB,OAAO,EACP,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,cAAc,EACd,oBAAoB,EAIpB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAmD,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * P15 — A/B routing manifest. Static-generator emits this file at deploy
+ * time (P6 + P13 contract). Per-provider edge routers (Cloud CDN /
+ * CloudFront L@E / Front Door rules / self-hosted Caddy gateway) all
+ * read this single shape so behaviour is identical across runtimes.
+ *
+ * Variant URL paths follow the convention:
+ *   control:  /<page-slug>
+ *   variant:  /_caelo-variant/<experimentId>/<variantLabel>/<page-slug>
+ *
+ * (Picked path-based over query-string-based so CDN cache keys aren't
+ * affected by query-string normalisation. See plans/phases/phase_15.)
+ */
+export interface ManifestVariant {
+    /** Owner-readable label (e.g. "A", "B", "control"). Stable across deploys. */
+    readonly label: string;
+    /** Bucket weight in [0, 100]. All variants for one experiment must sum to 100. */
+    readonly weight: number;
+    /**
+     * Path the edge router rewrites to when this variant wins. Includes
+     * the /_caelo-variant prefix for non-control variants; equal to
+     * `pageSlug` for control.
+     */
+    readonly path: string;
+}
+export interface ManifestExperiment {
+    /** Page slug the experiment runs on (e.g. "/home", "/pricing"). */
+    readonly pageSlug: string;
+    /** UUID — also the cookie partition key so two experiments don't collide. */
+    readonly experimentId: string;
+    readonly variants: ReadonlyArray<ManifestVariant>;
+}
+export interface RoutingManifest {
+    /** Bumped by the static generator on every deploy that changes routing. */
+    readonly manifestVersion: string;
+    /** All active experiments (only `status='active'` rows from cms_admin.experiments). */
+    readonly experiments: ReadonlyArray<ManifestExperiment>;
+}
+export declare const EMPTY_MANIFEST: RoutingManifest;
+/**
+ * Look up the active experiment for a given request URL. Returns null
+ * when no experiment matches the URL's page slug — caller should pass
+ * the request through unchanged.
+ */
+export declare function findExperimentForUrl(manifest: RoutingManifest, pathname: string): ManifestExperiment | null;
+/**
+ * Validates a manifest's invariants: every experiment's variant weights
+ * sum to 100, every variant has a non-empty label, the experimentId is
+ * a UUID, weights are non-negative. Returns null on success or a
+ * structured error string the static generator surfaces in audit. The
+ * runtime callers (edge routers) do NOT re-validate per request — they
+ * trust the deploy-time validation. This function is primarily for
+ * tests + the deploy step.
+ */
+export declare function validateManifest(manifest: RoutingManifest): string | null;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED,eAAO,MAAM,cAAc,EAAE,eAG5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,MAAM,GACf,kBAAkB,GAAG,IAAI,CAK3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAoBzE"}

package/dist/manifest.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MPL-2.0
+export const EMPTY_MANIFEST = {
+    manifestVersion: "0",
+    experiments: [],
+};
+/**
+ * Look up the active experiment for a given request URL. Returns null
+ * when no experiment matches the URL's page slug — caller should pass
+ * the request through unchanged.
+ */
+export function findExperimentForUrl(manifest, pathname) {
+    for (const ex of manifest.experiments) {
+        if (ex.pageSlug === pathname)
+            return ex;
+    }
+    return null;
+}
+/**
+ * Validates a manifest's invariants: every experiment's variant weights
+ * sum to 100, every variant has a non-empty label, the experimentId is
+ * a UUID, weights are non-negative. Returns null on success or a
+ * structured error string the static generator surfaces in audit. The
+ * runtime callers (edge routers) do NOT re-validate per request — they
+ * trust the deploy-time validation. This function is primarily for
+ * tests + the deploy step.
+ */
+export function validateManifest(manifest) {
+    for (const ex of manifest.experiments) {
+        if (!ex.experimentId.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)) {
+            return `experiment ${ex.experimentId} is not a UUID`;
+        }
+        if (ex.variants.length === 0) {
+            return `experiment ${ex.experimentId} has no variants`;
+        }
+        let total = 0;
+        for (const v of ex.variants) {
+            if (!v.label)
+                return `experiment ${ex.experimentId}: variant has empty label`;
+            if (v.weight < 0)
+                return `experiment ${ex.experimentId}: variant ${v.label} has negative weight`;
+            total += v.weight;
+        }
+        if (total !== 100) {
+            return `experiment ${ex.experimentId}: variant weights sum to ${total}, expected 100`;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,mCAAmC;AA4CnC,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC7C,eAAe,EAAE,GAAG;IACpB,WAAW,EAAE,EAAE;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAyB,EACzB,QAAgB;IAEhB,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,EAAE,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAyB;IACxD,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,iEAAiE,CAAC,EAAE,CAAC;YAC9F,OAAO,cAAc,EAAE,CAAC,YAAY,gBAAgB,CAAC;QACvD,CAAC;QACD,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,cAAc,EAAE,CAAC,YAAY,kBAAkB,CAAC;QACzD,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC,CAAC,CAAC,KAAK;gBAAE,OAAO,cAAc,EAAE,CAAC,YAAY,2BAA2B,CAAC;YAC9E,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;gBACd,OAAO,cAAc,EAAE,CAAC,YAAY,aAAa,CAAC,CAAC,KAAK,sBAAsB,CAAC;YACjF,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;QACpB,CAAC;QACD,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,OAAO,cAAc,EAAE,CAAC,YAAY,4BAA4B,KAAK,gBAAgB,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/router.d.ts

@@ -0,0 +1,31 @@
+/**
+ * P15 — generic edge-router request handler. The provider-specific
+ * shims (gcp.ts, aws.ts, azure.ts) wrap this in their respective
+ * runtime contracts (Cloud Run handler, Lambda@Edge handler, Front
+ * Door rules engine), but the routing decision itself is identical.
+ *
+ * One function. Three runtimes. Same hash → same variant → same path
+ * rewrite, every time.
+ */
+import { buildAssignmentLog } from "./assignment.js";
+import { type RoutingManifest } from "./manifest.js";
+export interface EdgeRequestSummary {
+    /** URL pathname only (e.g. "/about"). Query string ignored for routing. */
+    readonly pathname: string;
+    /** The current request's `caelo_visitor_id` cookie value, if any. */
+    readonly visitorIdCookie: string | null;
+}
+export interface EdgeRouteDecision {
+    /** Final pathname the runtime should serve (control or variant). */
+    readonly rewritePathname: string;
+    /** Visitor id the runtime should set as `caelo_visitor_id` (mint when absent). */
+    readonly setVisitorId: string;
+    /**
+     * Assignment-log payload to emit through the runtime's logger.
+     * Null when the request didn't match any experiment — runtime should
+     * NOT emit anything in that case (avoids log spam on every static asset).
+     */
+    readonly logEntry: ReturnType<typeof buildAssignmentLog> | null;
+}
+export declare function routeRequest(manifest: RoutingManifest, req: EdgeRequestSummary): EdgeRouteDecision;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAiB,kBAAkB,EAAiB,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,GAAG,IAAI,CAAC;CACjE;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,kBAAkB,GACtB,iBAAiB,CAyBnB"}

package/dist/router.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * P15 — generic edge-router request handler. The provider-specific
+ * shims (gcp.ts, aws.ts, azure.ts) wrap this in their respective
+ * runtime contracts (Cloud Run handler, Lambda@Edge handler, Front
+ * Door rules engine), but the routing decision itself is identical.
+ *
+ * One function. Three runtimes. Same hash → same variant → same path
+ * rewrite, every time.
+ */
+import { assignVariant, buildAssignmentLog, mintVisitorId } from "./assignment.js";
+import { findExperimentForUrl } from "./manifest.js";
+export function routeRequest(manifest, req) {
+    const visitorId = req.visitorIdCookie ?? mintVisitorId();
+    const experiment = findExperimentForUrl(manifest, req.pathname);
+    if (!experiment) {
+        return {
+            rewritePathname: req.pathname,
+            setVisitorId: visitorId,
+            logEntry: null,
+        };
+    }
+    const variant = assignVariant({
+        visitorId,
+        manifestVersion: manifest.manifestVersion,
+        experiment,
+    });
+    return {
+        rewritePathname: variant.path,
+        setVisitorId: visitorId,
+        logEntry: buildAssignmentLog({
+            experimentId: experiment.experimentId,
+            variant,
+            visitorId,
+            manifestVersion: manifest.manifestVersion,
+        }),
+    };
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAwB,MAAM,eAAe,CAAC;AAsB3E,MAAM,UAAU,YAAY,CAC1B,QAAyB,EACzB,GAAuB;IAEvB,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,IAAI,aAAa,EAAE,CAAC;IACzD,MAAM,UAAU,GAAG,oBAAoB,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;YACL,eAAe,EAAE,GAAG,CAAC,QAAQ;YAC7B,YAAY,EAAE,SAAS;YACvB,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,aAAa,CAAC;QAC5B,SAAS;QACT,eAAe,EAAE,QAAQ,CAAC,eAAe;QACzC,UAAU;KACX,CAAC,CAAC;IACH,OAAO;QACL,eAAe,EAAE,OAAO,CAAC,IAAI;QAC7B,YAAY,EAAE,SAAS;QACvB,QAAQ,EAAE,kBAAkB,CAAC;YAC3B,YAAY,EAAE,UAAU,CAAC,YAAY;YACrC,OAAO;YACP,SAAS;YACT,eAAe,EAAE,QAAQ,CAAC,eAAe;SAC1C,CAAC;KACH,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@caelo-cms/edge-router",
+  "version": "0.10.23",
+  "private": false,
+  "license": "MPL-2.0",
+  "description": "Locale-aware edge request router for Caelo CMS deployments — shared by the provisioning stacks' edge handlers (CDN URL-strategy routing) and the static generator.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caelo-cms/caelo-cms.git",
+    "directory": "packages/edge-router"
+  },
+  "homepage": "https://github.com/caelo-cms/caelo-cms#readme",
+  "bugs": "https://github.com/caelo-cms/caelo-cms/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc -b",
+    "build": "tsc -b --force",
+    "prepublishOnly": "tsc -b --force"
+  },
+  "dependencies": {}
+}

package/src/assignment.ts

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P15 — stable-hash A/B variant assignment.
+ *
+ * MUST produce byte-identical results across all four runtimes:
+ *   - self-hosted (P13 Caddy gateway)
+ *   - GCP edge router (Cloud Run header rule)
+ *   - AWS edge router (Lambda@Edge)
+ *   - Azure edge router (Front Door rules engine)
+ *
+ * Drift between runtimes means a visitor sees different variants
+ * depending on which provider serves them — silent A/B contamination.
+ * The byte-identity test in `index.test.ts` asserts a fixed corpus of
+ * (visitorId, manifestVersion, experimentId) tuples maps to the same
+ * variant label on every implementation.
+ *
+ * Algorithm: FNV-1a 32-bit hash of (visitorId + ":" + experimentId +
+ * ":" + manifestVersion). The 32-bit space mod 100 gives a bucket in
+ * [0, 99]; cumulative variant weights determine the variant. Pure +
+ * deterministic; no randomness, no time, no provider-specific code.
+ */
+
+import type { ManifestExperiment, ManifestVariant } from "./manifest.js";
+
+/**
+ * FNV-1a 32-bit. Standard offset basis 0x811c9dc5, prime 0x01000193.
+ * Implemented in plain TypeScript so every runtime (V8 / SpiderMonkey
+ * / Node L@E sandbox / Bun) produces byte-identical output.
+ */
+export function fnv1a32(input: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    // Multiply by FNV prime, keeping in 32-bit unsigned range. Math.imul
+    // is the cross-runtime way to do 32-bit-truncated integer multiply.
+    hash = Math.imul(hash, 0x01000193);
+  }
+  // Coerce back to unsigned 32-bit.
+  return hash >>> 0;
+}
+
+/**
+ * Compute the cumulative bucket boundaries for an experiment's variants.
+ * Stable: same input order → same boundaries → same assignment.
+ */
+function bucketBoundaries(variants: ReadonlyArray<ManifestVariant>): number[] {
+  let cum = 0;
+  return variants.map((v) => {
+    cum += v.weight;
+    return cum;
+  });
+}
+
+/**
+ * Assign a variant to a visitor for one experiment. Inputs:
+ *   - visitorId: stable opaque string from the `caelo_visitor_id` cookie.
+ *   - manifestVersion: bumped per deploy so a re-bucketing rolls out
+ *     atomically (operators occasionally need to re-randomize after a
+ *     biased early sample).
+ *   - experiment: the matched ManifestExperiment.
+ *
+ * Returns the chosen variant + its rewrite path. Pure; no I/O.
+ */
+export function assignVariant(opts: {
+  readonly visitorId: string;
+  readonly manifestVersion: string;
+  readonly experiment: ManifestExperiment;
+}): ManifestVariant {
+  const key = `${opts.visitorId}:${opts.experiment.experimentId}:${opts.manifestVersion}`;
+  const hash = fnv1a32(key);
+  const bucket = hash % 100;
+  const boundaries = bucketBoundaries(opts.experiment.variants);
+  for (let i = 0; i < boundaries.length; i += 1) {
+    if (bucket < (boundaries[i] ?? 0)) {
+      const v = opts.experiment.variants[i];
+      if (v) return v;
+    }
+  }
+  // Fallthrough (weights summed to 100 but float drift) — return last.
+  // Schema-level validation guarantees this doesn't happen in practice.
+  return opts.experiment.variants[opts.experiment.variants.length - 1] as ManifestVariant;
+}
+
+/**
+ * Format the assignment-log entry every runtime emits. Same JSON shape
+ * across providers so the P12A analytics plugin's per-provider log
+ * adapters can normalise into one `ab_assignment_aggregates` query.
+ */
+export interface AssignmentLogEntry {
+  readonly kind: "ab_assignment";
+  readonly experimentId: string;
+  readonly variantLabel: string;
+  readonly visitorId: string;
+  readonly manifestVersion: string;
+  readonly tsMs: number;
+}
+
+export function buildAssignmentLog(opts: {
+  readonly experimentId: string;
+  readonly variant: ManifestVariant;
+  readonly visitorId: string;
+  readonly manifestVersion: string;
+  readonly nowMs?: number;
+}): AssignmentLogEntry {
+  return {
+    kind: "ab_assignment",
+    experimentId: opts.experimentId,
+    variantLabel: opts.variant.label,
+    visitorId: opts.visitorId,
+    manifestVersion: opts.manifestVersion,
+    tsMs: opts.nowMs ?? Date.now(),
+  };
+}
+
+/**
+ * Mint a stable opaque visitor id when the request didn't carry the
+ * `caelo_visitor_id` cookie. Format: 16 hex bytes (128 bits — collision
+ * resistant for any plausible visitor population). Edge routers set
+ * this on the response cookie so the next request inherits the same id.
+ */
+export function mintVisitorId(): string {
+  const buf = new Uint8Array(16);
+  // crypto.getRandomValues is available in V8 / Node / L@E / Bun /
+  // every modern runtime; no Node Buffer fallback needed.
+  crypto.getRandomValues(buf);
+  return [...buf].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/index.test.ts

@@ -0,0 +1,254 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Edge-router byte-identity tests. These assert a fixed corpus of
+ * (visitorId, manifestVersion, experimentId) → (bucket, variantLabel)
+ * tuples. The numbers in this file are the ground truth; if you change
+ * the assignment algorithm, you change the contract for ALL FOUR
+ * runtime implementations (self-hosted P13 + GCP + AWS + Azure) and
+ * silently re-bucket every existing visitor's variant assignment. Don't
+ * change without bumping the manifestVersion in the same commit.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { assignVariant, buildAssignmentLog, fnv1a32, mintVisitorId } from "./assignment.js";
+import { findExperimentForUrl, validateManifest } from "./manifest.js";
+import { routeRequest } from "./router.js";
+
+describe("fnv1a32", () => {
+  it("matches the published FNV-1a-32 reference for a fixed corpus", () => {
+    // Reference values produced via the canonical algorithm —
+    // independent reimplementations against this list will catch
+    // off-by-one + signed-vs-unsigned bugs.
+    expect(fnv1a32("")).toBe(0x811c9dc5);
+    expect(fnv1a32("a")).toBe(0xe40c292c);
+    expect(fnv1a32("foobar")).toBe(0xbf9cf968);
+  });
+
+  it("is stable for identical input", () => {
+    const a = fnv1a32("visitor-12345:exp-abc:v3");
+    const b = fnv1a32("visitor-12345:exp-abc:v3");
+    expect(a).toBe(b);
+  });
+});
+
+describe("assignVariant", () => {
+  const experiment = {
+    pageSlug: "/home",
+    experimentId: "11111111-2222-3333-4444-555555555555",
+    variants: [
+      { label: "A", weight: 50, path: "/home" },
+      {
+        label: "B",
+        weight: 50,
+        path: "/_caelo-variant/11111111-2222-3333-4444-555555555555/B/home",
+      },
+    ],
+  } as const;
+
+  it("returns the same variant for the same (visitorId, manifestVersion, experimentId)", () => {
+    const a = assignVariant({
+      visitorId: "v-stable-1",
+      manifestVersion: "7",
+      experiment,
+    });
+    const b = assignVariant({
+      visitorId: "v-stable-1",
+      manifestVersion: "7",
+      experiment,
+    });
+    expect(a.label).toBe(b.label);
+  });
+
+  it("re-buckets when manifestVersion bumps (operator-triggered re-randomization)", () => {
+    // The whole point of bumping manifestVersion is to roll the dice
+    // afresh; for at least ONE visitor in 100, the assignment should
+    // differ between v=1 and v=2. Assert across a small population.
+    let differs = 0;
+    for (let i = 0; i < 100; i += 1) {
+      const v1 = assignVariant({
+        visitorId: `vis-${i}`,
+        manifestVersion: "1",
+        experiment,
+      });
+      const v2 = assignVariant({
+        visitorId: `vis-${i}`,
+        manifestVersion: "2",
+        experiment,
+      });
+      if (v1.label !== v2.label) differs += 1;
+    }
+    expect(differs).toBeGreaterThan(20);
+  });
+
+  it("respects bucket weights — 70/30 split lands within ±10pp over 1000 visitors", () => {
+    const skewed = {
+      pageSlug: "/pricing",
+      experimentId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+      variants: [
+        { label: "A", weight: 70, path: "/pricing" },
+        {
+          label: "B",
+          weight: 30,
+          path: "/_caelo-variant/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/B/pricing",
+        },
+      ],
+    } as const;
+    let aCount = 0;
+    for (let i = 0; i < 1000; i += 1) {
+      const v = assignVariant({
+        visitorId: `vis-${i}`,
+        manifestVersion: "1",
+        experiment: skewed,
+      });
+      if (v.label === "A") aCount += 1;
+    }
+    expect(aCount).toBeGreaterThan(600);
+    expect(aCount).toBeLessThan(800);
+  });
+
+  it("byte-identity corpus — these exact assignments must hold across all runtimes", () => {
+    // If this test starts failing because someone "improved" the hash,
+    // STOP. Every runtime's edge router (self-hosted Caddy gateway,
+    // GCP Cloud Run, AWS L@E, Azure Front Door) consumes this same
+    // contract. Change here = silent re-bucketing of every live
+    // experiment.
+    const corpus = [
+      { visitorId: "v-aaaaaaaa", manifestVersion: "1", expectedLabel: "A" },
+      { visitorId: "v-bbbbbbbb", manifestVersion: "1", expectedLabel: "A" },
+      { visitorId: "v-cccccccc", manifestVersion: "1", expectedLabel: "B" },
+      { visitorId: "v-dddddddd", manifestVersion: "1", expectedLabel: "A" },
+      { visitorId: "v-eeeeeeee", manifestVersion: "1", expectedLabel: "B" },
+    ];
+    for (const tc of corpus) {
+      const v = assignVariant({
+        visitorId: tc.visitorId,
+        manifestVersion: tc.manifestVersion,
+        experiment,
+      });
+      expect(v.label).toBe(tc.expectedLabel);
+    }
+  });
+});
+
+describe("validateManifest", () => {
+  const baseExperiment = {
+    pageSlug: "/p",
+    experimentId: "22222222-3333-4444-5555-666666666666",
+    variants: [
+      { label: "A", weight: 50, path: "/p" },
+      { label: "B", weight: 50, path: "/_caelo-variant/22222222-3333-4444-5555-666666666666/B/p" },
+    ],
+  } as const;
+
+  it("accepts a clean manifest", () => {
+    expect(validateManifest({ manifestVersion: "1", experiments: [baseExperiment] })).toBeNull();
+  });
+
+  it("rejects non-UUID experimentId", () => {
+    const bad = { ...baseExperiment, experimentId: "not-a-uuid" };
+    expect(validateManifest({ manifestVersion: "1", experiments: [bad] })).toContain("not a UUID");
+  });
+
+  it("rejects weights that don't sum to 100", () => {
+    const bad = {
+      ...baseExperiment,
+      variants: [
+        { label: "A", weight: 60, path: "/p" },
+        { label: "B", weight: 30, path: "/p-b" },
+      ],
+    };
+    expect(validateManifest({ manifestVersion: "1", experiments: [bad] })).toContain("sum to 90");
+  });
+});
+
+describe("routeRequest", () => {
+  const manifest = {
+    manifestVersion: "1",
+    experiments: [
+      {
+        pageSlug: "/home",
+        experimentId: "33333333-4444-5555-6666-777777777777",
+        variants: [
+          { label: "A", weight: 50, path: "/home" },
+          {
+            label: "B",
+            weight: 50,
+            path: "/_caelo-variant/33333333-4444-5555-6666-777777777777/B/home",
+          },
+        ],
+      },
+    ],
+  };
+
+  it("passes-through requests that don't match any experiment", () => {
+    const out = routeRequest(manifest, { pathname: "/about", visitorIdCookie: "v-1" });
+    expect(out.rewritePathname).toBe("/about");
+    expect(out.setVisitorId).toBe("v-1");
+    expect(out.logEntry).toBeNull();
+  });
+
+  it("rewrites + emits log when the request matches", () => {
+    const out = routeRequest(manifest, { pathname: "/home", visitorIdCookie: "v-aaaaaaaa" });
+    expect(["/home", "/_caelo-variant/33333333-4444-5555-6666-777777777777/B/home"]).toContain(
+      out.rewritePathname,
+    );
+    expect(out.logEntry).not.toBeNull();
+    expect(out.logEntry?.kind).toBe("ab_assignment");
+    expect(out.logEntry?.experimentId).toBe("33333333-4444-5555-6666-777777777777");
+  });
+
+  it("mints a visitor id when the cookie is absent", () => {
+    const out = routeRequest(manifest, { pathname: "/home", visitorIdCookie: null });
+    expect(out.setVisitorId).toMatch(/^[0-9a-f]{32}$/);
+  });
+});
+
+describe("findExperimentForUrl", () => {
+  it("finds by exact pageSlug match", () => {
+    const m = {
+      manifestVersion: "1",
+      experiments: [
+        {
+          pageSlug: "/home",
+          experimentId: "44444444-5555-6666-7777-888888888888",
+          variants: [{ label: "A", weight: 100, path: "/home" }],
+        },
+      ],
+    };
+    expect(findExperimentForUrl(m, "/home")?.experimentId).toBe(
+      "44444444-5555-6666-7777-888888888888",
+    );
+    expect(findExperimentForUrl(m, "/about")).toBeNull();
+  });
+});
+
+describe("buildAssignmentLog", () => {
+  it("produces the canonical log shape", () => {
+    const entry = buildAssignmentLog({
+      experimentId: "55555555-6666-7777-8888-999999999999",
+      variant: { label: "B", weight: 50, path: "/x" },
+      visitorId: "v-1",
+      manifestVersion: "3",
+      nowMs: 1700000000000,
+    });
+    expect(entry).toEqual({
+      kind: "ab_assignment",
+      experimentId: "55555555-6666-7777-8888-999999999999",
+      variantLabel: "B",
+      visitorId: "v-1",
+      manifestVersion: "3",
+      tsMs: 1700000000000,
+    });
+  });
+});
+
+describe("mintVisitorId", () => {
+  it("returns 32 hex chars", () => {
+    expect(mintVisitorId()).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it("each call is unique", () => {
+    expect(mintVisitorId()).not.toBe(mintVisitorId());
+  });
+});

package/src/index.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @caelo-cms/edge-router — P15.
+ *
+ * Provider-agnostic edge-routing logic for A/B experiments. The same
+ * hash → same variant → same rewrite path holds across self-hosted
+ * (P13 Caddy gateway) + GCP + AWS + Azure. Provider-specific shims
+ * land in `packages/provisioning/stacks/<provider>/edge-handler.ts`
+ * and import this package's `routeRequest` for the actual decision.
+ */
+
+export {
+  type AssignmentLogEntry,
+  assignVariant,
+  buildAssignmentLog,
+  fnv1a32,
+  mintVisitorId,
+} from "./assignment.js";
+export {
+  EMPTY_MANIFEST,
+  findExperimentForUrl,
+  type ManifestExperiment,
+  type ManifestVariant,
+  type RoutingManifest,
+  validateManifest,
+} from "./manifest.js";
+export { type EdgeRequestSummary, type EdgeRouteDecision, routeRequest } from "./router.js";

package/src/manifest.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P15 — A/B routing manifest. Static-generator emits this file at deploy
+ * time (P6 + P13 contract). Per-provider edge routers (Cloud CDN /
+ * CloudFront L@E / Front Door rules / self-hosted Caddy gateway) all
+ * read this single shape so behaviour is identical across runtimes.
+ *
+ * Variant URL paths follow the convention:
+ *   control:  /<page-slug>
+ *   variant:  /_caelo-variant/<experimentId>/<variantLabel>/<page-slug>
+ *
+ * (Picked path-based over query-string-based so CDN cache keys aren't
+ * affected by query-string normalisation. See plans/phases/phase_15.)
+ */
+
+export interface ManifestVariant {
+  /** Owner-readable label (e.g. "A", "B", "control"). Stable across deploys. */
+  readonly label: string;
+  /** Bucket weight in [0, 100]. All variants for one experiment must sum to 100. */
+  readonly weight: number;
+  /**
+   * Path the edge router rewrites to when this variant wins. Includes
+   * the /_caelo-variant prefix for non-control variants; equal to
+   * `pageSlug` for control.
+   */
+  readonly path: string;
+}
+
+export interface ManifestExperiment {
+  /** Page slug the experiment runs on (e.g. "/home", "/pricing"). */
+  readonly pageSlug: string;
+  /** UUID — also the cookie partition key so two experiments don't collide. */
+  readonly experimentId: string;
+  readonly variants: ReadonlyArray<ManifestVariant>;
+}
+
+export interface RoutingManifest {
+  /** Bumped by the static generator on every deploy that changes routing. */
+  readonly manifestVersion: string;
+  /** All active experiments (only `status='active'` rows from cms_admin.experiments). */
+  readonly experiments: ReadonlyArray<ManifestExperiment>;
+}
+
+export const EMPTY_MANIFEST: RoutingManifest = {
+  manifestVersion: "0",
+  experiments: [],
+};
+
+/**
+ * Look up the active experiment for a given request URL. Returns null
+ * when no experiment matches the URL's page slug — caller should pass
+ * the request through unchanged.
+ */
+export function findExperimentForUrl(
+  manifest: RoutingManifest,
+  pathname: string,
+): ManifestExperiment | null {
+  for (const ex of manifest.experiments) {
+    if (ex.pageSlug === pathname) return ex;
+  }
+  return null;
+}
+
+/**
+ * Validates a manifest's invariants: every experiment's variant weights
+ * sum to 100, every variant has a non-empty label, the experimentId is
+ * a UUID, weights are non-negative. Returns null on success or a
+ * structured error string the static generator surfaces in audit. The
+ * runtime callers (edge routers) do NOT re-validate per request — they
+ * trust the deploy-time validation. This function is primarily for
+ * tests + the deploy step.
+ */
+export function validateManifest(manifest: RoutingManifest): string | null {
+  for (const ex of manifest.experiments) {
+    if (!ex.experimentId.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)) {
+      return `experiment ${ex.experimentId} is not a UUID`;
+    }
+    if (ex.variants.length === 0) {
+      return `experiment ${ex.experimentId} has no variants`;
+    }
+    let total = 0;
+    for (const v of ex.variants) {
+      if (!v.label) return `experiment ${ex.experimentId}: variant has empty label`;
+      if (v.weight < 0)
+        return `experiment ${ex.experimentId}: variant ${v.label} has negative weight`;
+      total += v.weight;
+    }
+    if (total !== 100) {
+      return `experiment ${ex.experimentId}: variant weights sum to ${total}, expected 100`;
+    }
+  }
+  return null;
+}

package/src/router.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P15 — generic edge-router request handler. The provider-specific
+ * shims (gcp.ts, aws.ts, azure.ts) wrap this in their respective
+ * runtime contracts (Cloud Run handler, Lambda@Edge handler, Front
+ * Door rules engine), but the routing decision itself is identical.
+ *
+ * One function. Three runtimes. Same hash → same variant → same path
+ * rewrite, every time.
+ */
+
+import { assignVariant, buildAssignmentLog, mintVisitorId } from "./assignment.js";
+import { findExperimentForUrl, type RoutingManifest } from "./manifest.js";
+
+export interface EdgeRequestSummary {
+  /** URL pathname only (e.g. "/about"). Query string ignored for routing. */
+  readonly pathname: string;
+  /** The current request's `caelo_visitor_id` cookie value, if any. */
+  readonly visitorIdCookie: string | null;
+}
+
+export interface EdgeRouteDecision {
+  /** Final pathname the runtime should serve (control or variant). */
+  readonly rewritePathname: string;
+  /** Visitor id the runtime should set as `caelo_visitor_id` (mint when absent). */
+  readonly setVisitorId: string;
+  /**
+   * Assignment-log payload to emit through the runtime's logger.
+   * Null when the request didn't match any experiment — runtime should
+   * NOT emit anything in that case (avoids log spam on every static asset).
+   */
+  readonly logEntry: ReturnType<typeof buildAssignmentLog> | null;
+}
+
+export function routeRequest(
+  manifest: RoutingManifest,
+  req: EdgeRequestSummary,
+): EdgeRouteDecision {
+  const visitorId = req.visitorIdCookie ?? mintVisitorId();
+  const experiment = findExperimentForUrl(manifest, req.pathname);
+  if (!experiment) {
+    return {
+      rewritePathname: req.pathname,
+      setVisitorId: visitorId,
+      logEntry: null,
+    };
+  }
+  const variant = assignVariant({
+    visitorId,
+    manifestVersion: manifest.manifestVersion,
+    experiment,
+  });
+  return {
+    rewritePathname: variant.path,
+    setVisitorId: visitorId,
+    logEntry: buildAssignmentLog({
+      experimentId: experiment.experimentId,
+      variant,
+      visitorId,
+      manifestVersion: manifest.manifestVersion,
+    }),
+  };
+}