typespec-http-zod 0.26.0 → 0.27.0

package/dist/src/api.d.ts

@@ -83,6 +83,15 @@ export interface EmittedResponseHeader {
     readonly name: string;
     /** The TypeScript type of the value, so a server emitter can put it in a signature. */
     readonly type: string;
+    /**
+     * The Zod expression for the value, so a server can check what it is about to send.
+     *
+     * The TYPE above constrains what a handler may return at compile time; this constrains what
+     * actually goes on the wire, which is the same split `schema` and the contract types already make
+     * for a body. A value that crossed a boundary the type system cannot see into - a service binding,
+     * a cast - is exactly what it catches.
+     */
+    readonly schema: string;
     /** The document's `required: false`. */
     readonly optional: boolean;
 }
@@ -298,6 +307,8 @@ export interface EmittedRoute {
      * request. It read as "the parameters" and was the field an adopter reached for first.
      */
     readonly pathSchema: string | undefined;
+    /** Cookie parameters, as one object schema, or `undefined` where the operation declares none. */
+    readonly cookieSchema: string | undefined;
     readonly querySchema: string | undefined;
     /**
      * The query OBJECT itself, which differs from `querySchema` only where a form-exploded record or
@@ -416,6 +427,11 @@ export interface RouteSchemaNames {
      */
     readonly queryFields: string | undefined;
     readonly header: string | undefined;
+    /**
+     * Cookie parameters. **Optional on the interface, so a server emitter that does not read it yet
+     * still compiles** - this arrived after the other four and two emitters consume this type.
+     */
+    readonly cookie?: string | undefined;
     readonly body: string | undefined;
     /**
      * The identifier each response's body is declared under, parallel to `EmittedRoute.responses` and
@@ -428,6 +444,11 @@ export interface RouteSchemaNames {
     readonly arms: readonly {
         readonly status: StatusKey;
         readonly schema: string | undefined;
+        /**
+         * The identifier holding this status's declared response headers, where it declares any.
+         * **Optional on the interface**, so a server emitter that does not check them yet still builds.
+         */
+        readonly headers?: string | undefined;
     }[];
     /**
      * The `readonly ResponseArm[]` const - what the operation may answer with, and with which body.

package/dist/src/api.js

@@ -316,6 +316,14 @@ function responsesOf(program, operation, registry) {
                     entry.headers.push({
                         name,
                         type: typeToTs(program, property.type),
+                        /**
+                         * **The Zod expression, which used to be discarded here.** Every REQUEST parameter
+                         * goes through `expressionForProperty` a few hundred lines below; a response header
+                         * went through `typeToTs` and nothing else, so the emitted arm carried a name and an
+                         * optionality and no way to check a value. A response body that breaks its schema
+                         * throws `ResponseContractError`; a header that breaks its own was served.
+                         */
+                        schema: registry.expressionForProperty(property),
                         optional: property.optional,
                     });
                 }
@@ -968,9 +976,39 @@ function mediaTypeDecoded(declared) {
             .map((entry) => entry.trim().replace(/^"|"$/g, ""));
     if (values === undefined || values.length === 0)
         return declared;
+    /**
+     * **A declared media RANGE admits the types inside it, and a literal admits only itself.**
+     *
+     * \`@header contentType: "text/*"\` published \`z.literal("text/*")\`, so the only request that
+     * satisfied it was one sending the range itself as its \`Content-Type\`, which no client does.
+     * Measured before this existed: \`text/plain\` and \`text/html\` both answered 400 on a route whose
+     * document declares the whole \`text\` group.
+     *
+     * A template literal is the Zod counterpart of the TypeScript type the contract already uses for
+     * a range, so the validator and the handler's own type say the same thing.
+     */
+    const admitted = values.map((value) => {
+        /**
+         * **The full wildcard admits every media type, so there is nothing left to match on.**
+         *
+         * Spelled as a template literal it becomes the prefix `*` + `/`, which matches only a
+         * Content-Type whose text begins with the range's own first two characters. Measured on the
+         * emitted schema: `application/json`, `text/plain` and `image/png` were all REFUSED and the
+         * literal `*` + `/*` was the one value accepted, which is the defect the range branch exists
+         * to remove rather than to respell. A consumer declares this on a file upload that takes
+         * whatever the caller sends.
+         */
+        if (value === "*/*")
+            return "z.string()";
+        return value.endsWith("/*")
+            ? `z.templateLiteral([${JSON.stringify(value.slice(0, -1))}, z.string()])`
+            : `z.literal(${JSON.stringify(value)})`;
+    });
+    const schema = admitted.length === 1 ? (admitted[0] ?? declared) : `z.union([${admitted.join(", ")}])`;
+    const ranged = values.some((value) => value.endsWith("/*")) ? schema : declared;
     // Lowercased only when every declared value already is, so an oddly-cased one keeps matching.
     const normalise = values.every((value) => value === value.toLowerCase()) ? ".toLowerCase()" : "";
-    return `z.preprocess((raw) => (typeof raw === "string" ? (raw.split(";")[0] ?? "").trim()${normalise} : raw), ${declared})`;
+    return `z.preprocess((raw) => (typeof raw === "string" ? (raw.split(";")[0] ?? "").trim()${normalise} : raw), ${ranged})`;
 }
 function parameterSchemasOf(program, operation, registry, segments, 
 /** The names of a query string written into the route itself, which no parameter may gather. */
@@ -983,7 +1021,22 @@ literalQueryNames) {
         .filter((parameter) => parameter.type === "query")
         .map((parameter) => parameter.name);
     for (const parameter of operation.parameters.parameters) {
-        if (parameter.type !== "path" && parameter.type !== "query" && parameter.type !== "header") {
+        /**
+         * **`cookie` is here because `@typespec/http` puts it here**, and excluding it was silent.
+         * `HttpOperationParameter` discriminates on `"header" | "cookie" | "query" | "path"`, and this
+         * filter named three of the four, so a `@cookie` reached no validator, no handler input and no
+         * diagnostic while `@typespec/openapi3` published it as `in: cookie, required: true`. A
+         * requirement the document states and the server cannot see is the defect class this package
+         * exists to remove, and a cookie is where a session and a CSRF token normally live.
+         *
+         * The exclusion was by omission rather than by a `never` check, which is why TypeScript never
+         * objected; every other place that reads `parameter.type` handles an encoding question a cookie
+         * does not have, since `CookieOptions` carries only a name.
+         */
+        if (parameter.type !== "path" &&
+            parameter.type !== "query" &&
+            parameter.type !== "header" &&
+            parameter.type !== "cookie") {
             continue;
         }
         /**
@@ -1102,6 +1155,7 @@ literalQueryNames) {
     };
     const query = shape("query");
     return {
+        cookie: shape("cookie"),
         path: shape("path"),
         query: query === undefined
             ? undefined
@@ -1299,6 +1353,7 @@ export function collectRoutes(program, registry, service) {
                 ...(() => {
                     const split = withVisibility(program, requestVisibility, () => parameterSchemasOf(program, operation, registry, template.segments, template.literalQuery.map(([name]) => name)));
                     return {
+                        cookieSchema: split.cookie,
                         pathSchema: split.path,
                         querySchema: split.query,
                         queryFieldsSchema: split.queryFields,
@@ -1452,13 +1507,30 @@ function renderSchemas(registry, externals, routeDeclarations, compileSchemas) {
          * parse - the walk captures the reference while it is still in the temporal dead zone, so the
          * failure surfaces at request time rather than at import.
          *
-         * **Keyed on `annotated`, the fact the registry already holds** - it is set exactly when the
-         * declaration is deferred, which is exactly when `z.lazy()` is written - rather than on the
-         * shape of the emitted text. A model on a cycle whose back edge sits on a GETTER is a different
-         * case and is compiled like any other: measured, it parses, because a getter is not resolved
-         * until something reads it.
+         * **CYCLE MEMBERSHIP decides this, not deferral, and that took a zod upgrade to learn.**
+         *
+         * It was keyed on `annotated` - set exactly when the declaration is deferred, which is exactly
+         * when `z.lazy()` is written - on the measurement that a model whose back edge sits on a GETTER
+         * compiled and parsed fine. That was true on zod 4.5.2 and is false on 4.6.5, which made the
+         * recursive parse state weak. The failure moved from the deferred declaration to the one that
+         * REFERENCES it, which was still being compiled:
+         *
+         * ```
+         * const branchSchema = z.lazy(() => z.union([nodeSchema, z.string()]));
+         * const nodeSchema = z.compile(z.strictObject({ ..., branch: branchSchema.exactOptional() }));
+         * nodeSchema.safeParse({ label: "a", attributes: {} });
+         * zod 4.5.2: true
+         * zod 4.6.5: TypeError: Cannot read properties of undefined (reading '_zod')
+         * ```
+         *
+         * Bisected: naming a compiled schema from inside a `z.lazy()` body is the whole trigger, and
+         * the self-referencing getter is not needed for it. So the same rule the registry already
+         * applies to structural types applies here - every member of the cycle, not only the deferred
+         * one - and `structural` is the fact it already holds for exactly that set.
+         *
+         * The peer range admits 4.6, so this reached a running server on the first parse.
          */
-        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${compiled(d.source, compileSchemas && d.annotated !== true)};\n`;
+        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${compiled(d.source, compileSchemas && d.structural === undefined)};\n`;
     });
     /**
      * **Written only when something in the file names it**, like the `ResponseArm` import below and for
@@ -1633,6 +1705,7 @@ function nameRouteSchemas(routes, compileSchemas) {
         const query = declare("Query", gathers && queryFields !== undefined && route.queryFieldsSchema !== undefined
             ? route.querySchema?.replace(route.queryFieldsSchema, queryFields)
             : route.querySchema);
+        const cookie = declare("Cookie", route.cookieSchema);
         const negotiating = shared.has(`${route.verb} ${route.path}`);
         const header = declare("Header", negotiating ? route.negotiatedHeaderSchema : route.headerSchema);
         // A raw body is read as text, never parsed, so it has no validator - the bytes are the contract.
@@ -1643,13 +1716,28 @@ function nameRouteSchemas(routes, compileSchemas) {
          */
         const declaredBodies = new Map();
         const arms = route.responses.map((response) => {
-            if (response.schema === undefined)
-                return { status: response.status, schema: undefined };
+            const suffix = response.status === "default" ? "Default" : String(response.status);
+            /**
+             * The headers this status declares, as one object schema, so a server can check what it is
+             * about to send the way it already checks the body.
+             *
+             * **A plain `z.object`, which strips.** A response carries headers the document does not
+             * declare - `Content-Type` among them, which the server sets itself - and those are not a
+             * contract violation. What is checked is that every header the document DOES declare carries
+             * a value the document permits.
+             */
+            const headers = response.headers.length === 0
+                ? undefined
+                : declare(`Response${suffix}Headers`, `z.object({\n${response.headers
+                    .map((header) => `\t${objectKey(header.name)}: ${header.schema},`)
+                    .join("\n")}\n})`);
+            if (response.schema === undefined) {
+                return { status: response.status, schema: undefined, headers };
+            }
             if (!declaredBodies.has(response.schema)) {
-                const suffix = response.status === "default" ? "Default" : String(response.status);
                 declaredBodies.set(response.schema, declare(`Response${suffix}`, response.schema));
             }
-            return { status: response.status, schema: declaredBodies.get(response.schema) };
+            return { status: response.status, schema: declaredBodies.get(response.schema), headers };
         });
         const responses = schemaConst(route.operationId, "Responses");
         declarations.push(`export const ${responses} = ${responseArmsOf(route, arms)} satisfies readonly ResponseArm[];`);
@@ -1659,6 +1747,7 @@ function nameRouteSchemas(routes, compileSchemas) {
             query,
             queryFields: gathers ? queryFields : query,
             header,
+            cookie,
             body,
             arms,
             responses,
@@ -1741,7 +1830,9 @@ function collectRequestTypes(program, registry, service) {
                 const extraProperties = operation.parameters.parameters
                     .filter((parameter) => parameter.type === "path" ||
                     parameter.type === "query" ||
-                    parameter.type === "header")
+                    parameter.type === "header" ||
+                    // The second half of the same omission: a validator with no matching type.
+                    parameter.type === "cookie")
                     /**
                      * Named as the WIRE names it, which is what the emitted validator keys on.
                      * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
@@ -2058,7 +2149,7 @@ type Identical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends
  * that does not.
  */
 /**
- * \u26a0\ufe0f **An optional property is \`?: T\` here and \`?: T | undefined\` in the contract type, and that is
+ * **An optional property is \`?: T\` here and \`?: T | undefined\` in the contract type, and that is
  * deliberate on both sides.**
  *
  * The validator emits \`.exactOptional()\`, so what ARRIVES is absent or a value - JSON cannot carry an
@@ -2121,8 +2212,8 @@ type Declared<T> = T extends (...args: never[]) => unknown
 			: T;
 
 /**
- * \u26a0\ufe0f **The constraint is what fails the build.** \`Identical<A, B> & true\` merely produces an odd
- * type when the two disagree, and a type alias to an odd type compiles fine \u2014 66 assertions that
+ * **The constraint is what fails the build.** \`Identical<A, B> & true\` merely produces an odd
+ * type when the two disagree, and a type alias to an odd type compiles fine - 66 assertions that
  * assert nothing. Only a constraint violation is an error.
  */
 type MustHold<T extends true> = T;

package/dist/src/constraints.d.ts

@@ -15,6 +15,27 @@ import { type Program, type Type } from "@typespec/compiler";
  * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
 export declare function applyConstraints(program: Program, expression: string, target: Type): string;
+/**
+ * **Whether a `@pattern` can be proven safe against catastrophic backtracking.**
+ *
+ * A pure verdict, with no program and no report. The judgement belongs to the
+ * `redos-prone-pattern` LINTER rule rather than to emission, because the spec is valid, the
+ * document is correct and the emitted regex is exactly the published one: what is wrong is a cost
+ * no artefact states, which is the case TypeSpec reserves for a linter.
+ *
+ * **The engine is the one Zod runs on**, so the analysis carries whichever flag
+ * {@link patternToRegex} will emit. Analysing `\p{L}+` with `unicode: false` asks about a different
+ * expression from the one that runs - the identity escape for `p` - and a verdict about the wrong
+ * pattern is worth nothing whichever way it comes out.
+ *
+ * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
+ * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
+ * the timeout is judged the same way as one it decides against. Measured over a realistic spread of
+ * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
+ * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
+ * ordinary and takes **11 seconds** on a 29-character input.
+ */
+export declare function patternIsProvablySafe(pattern: string): boolean;
 /**
  * A `@pattern` string becomes a regex literal - **verbatim**.
  *
@@ -37,3 +58,28 @@ export declare function applyConstraints(program: Program, expression: string, t
  * instead of guessing at an equivalence.
  */
 export declare function patternToRegex(pattern: string): string;
+/**
+ * Whether the expression is one the `u` flag accepts, which is how a JSON Schema reader compiles it.
+ *
+ * **The flag is part of the contract, and leaving it off was the divergence.** A bare `/.../` makes
+ * `\p{L}` an identity escape for the letter `p`, so the expression the server ran was not the
+ * expression the spec author wrote. Measured against Ajv on the published document, with every
+ * verdict inverted:
+ *
+ * ```
+ * value        document (Ajv)   emitted validator
+ * "abc"        VALID            INVALID
+ * "Unicode"    VALID            INVALID
+ * "p{L}"       INVALID          VALID
+ * ```
+ *
+ * Ajv compiles a JSON Schema `pattern` with `u` by default, so carrying it here is not a rule laid
+ * on top of the contract; it is the contract.
+ *
+ * **Only when the pattern compiles under it.** `u` makes several ordinary spellings an error - a
+ * redundant `\-` outside a character class, a lone `]` or `{`, an identity escape such as `\a` - and
+ * 5 of 15 realistic patterns tested fail to compile with it. Those keep the bare form they already
+ * had, and {@link reportNonUnicodePattern} says so at build time, because a reader of the document
+ * cannot compile them either.
+ */
+export declare function unicodeSafe(pattern: string): boolean;

package/dist/src/constraints.js

@@ -1,4 +1,6 @@
-import { getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
+import { getEncode, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
+import { isSafePattern } from "redos-detector";
+import { reportDiagnostic } from "./lib.js";
 /**
  * Constraint decorators -> the Zod modifiers that enforce them.
  *
@@ -23,26 +25,165 @@ export function applyConstraints(program, expression, target) {
     const minItems = getMinItems(program, target);
     const maxItems = getMaxItems(program, target);
     const pattern = getPattern(program, target);
+    const minExclusive = getMinValueExclusive(program, target);
+    const maxExclusive = getMaxValueExclusive(program, target);
+    /**
+     * **A numeric bound says nothing about a value carried as text.** `@encode(string)` is legal on a
+     * numeric property and makes the wire value a string, so the expression here is `z.string()` while
+     * `@minValue` is still a statement about the number it spells. Folding the two together emitted a
+     * LENGTH check: `@minValue(1)` accepted `"0"`, and `@minValue(100)` refused `"150"`. The exclusive
+     * form was worse - `z.string().gt(0)` is not a function, so the module threw on import and took
+     * the whole service down with it.
+     *
+     * It cannot be enforced either, and not for want of a mechanism: the document publishes `minimum`
+     * on a `type: string` schema, which JSON Schema ignores, so a validator that checked it would
+     * refuse payloads the published contract accepts. That is the same defect in the other direction,
+     * and this package's rule is that the two artefacts agree. So the bound is dropped and reported.
+     */
+    const encodedAsText = encodesAsString(program, target);
+    const numeric = [minValue, maxValue, minExclusive, maxExclusive].some((bound) => bound !== undefined);
+    if (encodedAsText && numeric) {
+        reportDiagnostic(program, {
+            code: "unenforceable-encoded-bound",
+            format: {
+                name: target.kind === "ModelProperty" || target.kind === "Scalar" ? target.name : "",
+            },
+            target,
+        });
+    }
     // `@minLength`/`@minValue`/`@minItems` all land on Zod's `.min()`; they are distinguished by the
-    // type they are legal on, which TypeSpec has already checked by the time we get here.
-    const min = minLength ?? minValue ?? minItems;
-    const max = maxLength ?? maxValue ?? maxItems;
+    // type they are legal on, which TypeSpec has already checked by the time we get here - except
+    // under `@encode(string)`, where the type they are legal on is not the type emitted.
+    const min = minLength ?? (encodedAsText ? undefined : minValue) ?? minItems;
+    const max = maxLength ?? (encodedAsText ? undefined : maxValue) ?? maxItems;
     if (min !== undefined)
         result += `.min(${min})`;
     if (max !== undefined)
         result += `.max(${max})`;
     // Exclusive bounds are a distinct question from inclusive ones - `z.number().positive()` is
     // `.gt(0)`, and emitting `.min(0)` for it would accept a zero share count or a zero spot rate.
-    const minExclusive = getMinValueExclusive(program, target);
-    const maxExclusive = getMaxValueExclusive(program, target);
-    if (minExclusive !== undefined)
+    if (!encodedAsText && minExclusive !== undefined)
         result += `.gt(${minExclusive})`;
-    if (maxExclusive !== undefined)
+    if (!encodedAsText && maxExclusive !== undefined)
         result += `.lt(${maxExclusive})`;
-    if (pattern !== undefined)
+    if (pattern !== undefined) {
+        reportNonUnicodePattern(program, pattern, target);
         result += `.regex(${patternToRegex(pattern)})`;
+    }
     return result;
 }
+/**
+ * Whether the value this type puts on the wire is text because `@encode` says so. Read from the
+ * property and then from its scalar, which is where an encoding declared once for a named scalar
+ * lives.
+ */
+function encodesAsString(program, target) {
+    if (target.kind !== "ModelProperty" && target.kind !== "Scalar")
+        return false;
+    const own = getEncode(program, target);
+    const scalar = own === undefined && target.kind === "ModelProperty" && target.type.kind === "Scalar"
+        ? getEncode(program, target.type)
+        : undefined;
+    return (own ?? scalar)?.type.name === "string";
+}
+/**
+ * How long one pattern may be analysed before the answer is "could not prove it".
+ *
+ * **Bounded, because the analysis is itself exponential in the bad case.** Measured: `^(a|a)+$`
+ * takes 1.6 seconds to decide, and a build should not stall on a pattern whose whole problem is that
+ * it does too much work. A pattern that cannot be decided inside this is one this emitter cannot
+ * certify, which is what the warning says.
+ */
+const ANALYSIS_TIMEOUT_MS = 500;
+/**
+ * Patterns already judged, keyed on the text, which is the only input the verdict depends on.
+ *
+ * The analysis costs up to {@link ANALYSIS_TIMEOUT_MS} a pattern, and one pattern text commonly
+ * recurs across declarations - `^\\d{4}-\\d{2}-\\d{2}$` appears on several scalars in more than one
+ * consumer spec - so each distinct text is analysed once per process.
+ */
+const verdicts = new Map();
+/**
+ * Which declarations have already been reported, per program.
+ *
+ * **Per PROGRAM, and that distinction is the whole reason this is a `WeakMap`.** One scalar carrying
+ * a pattern is reached once per USE - the reference service reaches a single scalar 153 times - and
+ * three identical warnings pointing at one declaration are noise a reader learns to skip. But a
+ * module-level "already said that" would also silence the second compile in a watch session, or the
+ * second service in one program, which is a warning lost rather than a warning tidied. Keyed on the
+ * program, it is emptied whenever the program is.
+ *
+ * The verdict cache above is different and is deliberately global: it is a pure function of the
+ * pattern text, so it cannot be wrong for a later program.
+ */
+const reported = new WeakMap();
+/**
+ * **Whether this diagnostic has already been raised against this declaration.**
+ *
+ * Keyed on the code as well as the target. Keying on the target alone once made the memo shared
+ * between every pattern diagnostic, so whichever ran first claimed the declaration and silenced
+ * the rest: measured on `^(\w+\s?)*\-$`, one warning where two were due. The ReDoS judgement has
+ * since moved to a linter rule, which reports per declaration by construction, so that pairing can
+ * no longer meet here - but a memo keyed on the target alone is the wrong shape for the next
+ * diagnostic added beside this one, and costs nothing to keep right.
+ *
+ * The de-duplication itself is per declaration, because emission reaches a scalar once per USE -
+ * 153 times for a single scalar in the reference service - and repeating one warning that often
+ * is noise a reader learns to skip, which is how a real one gets missed.
+ */
+function firstReportOf(program, code, target) {
+    let byCode = reported.get(program);
+    if (byCode === undefined) {
+        byCode = new Map();
+        reported.set(program, byCode);
+    }
+    let already = byCode.get(code);
+    if (already === undefined) {
+        already = new WeakSet();
+        byCode.set(code, already);
+    }
+    if (already.has(target))
+        return false;
+    already.add(target);
+    return true;
+}
+/**
+ * **Whether a `@pattern` can be proven safe against catastrophic backtracking.**
+ *
+ * A pure verdict, with no program and no report. The judgement belongs to the
+ * `redos-prone-pattern` LINTER rule rather than to emission, because the spec is valid, the
+ * document is correct and the emitted regex is exactly the published one: what is wrong is a cost
+ * no artefact states, which is the case TypeSpec reserves for a linter.
+ *
+ * **The engine is the one Zod runs on**, so the analysis carries whichever flag
+ * {@link patternToRegex} will emit. Analysing `\p{L}+` with `unicode: false` asks about a different
+ * expression from the one that runs - the identity escape for `p` - and a verdict about the wrong
+ * pattern is worth nothing whichever way it comes out.
+ *
+ * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
+ * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
+ * the timeout is judged the same way as one it decides against. Measured over a realistic spread of
+ * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
+ * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
+ * ordinary and takes **11 seconds** on a 29-character input.
+ */
+export function patternIsProvablySafe(pattern) {
+    let safe = verdicts.get(pattern);
+    if (safe === undefined) {
+        try {
+            safe = isSafePattern(pattern, {
+                unicode: unicodeSafe(pattern),
+                timeout: ANALYSIS_TIMEOUT_MS,
+            }).safe;
+        }
+        catch {
+            // A pattern the analyser cannot even parse is not one to make a claim about.
+            safe = true;
+        }
+        verdicts.set(pattern, safe);
+    }
+    return safe;
+}
 /**
  * A `@pattern` string becomes a regex literal - **verbatim**.
  *
@@ -65,5 +206,87 @@ export function applyConstraints(program, expression, target) {
  * instead of guessing at an equivalence.
  */
 export function patternToRegex(pattern) {
-    return `/${pattern.replace(/\//g, "\\/")}/`;
+    return `/${escapeSlashes(pattern)}/${unicodeSafe(pattern) ? "u" : ""}`;
+}
+/**
+ * **Escapes the slashes a regex literal needs escaped, and only those.**
+ *
+ * A `.replace(/\//g, "\\/")` escapes unconditionally, so a pattern that already spelled a slash
+ * as an escape had its backslash doubled: `^\/api\/v[0-9]+$` became the literal
+ * `/^\\/api\\/v[0-9]+$/u`, which ends at the third slash and reads `api` as flags. Measured on
+ * that pattern: `tsp compile` EXIT=0 and silent, `node` refused the emitted module with
+ * `SyntaxError: Invalid regular expression flags`, and `tsc` reported `TS1127: Invalid character`.
+ * A path regex is the most ordinary place a slash appears, and no fixture here had ever carried
+ * one - nor does any of the 67 specs in `@typespec/http-specs`.
+ *
+ * A backslash takes the character after it with it, so `\/` is already escaped and is left alone,
+ * while `\\` is a literal backslash and a slash following it still needs escaping. `\/` remains a
+ * legal identity escape under the `u` flag, so this does not change which patterns can carry it.
+ */
+function escapeSlashes(pattern) {
+    let escaped = "";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "\\") {
+            escaped += character + (pattern[index + 1] ?? "");
+            index += 1;
+            continue;
+        }
+        escaped += character === "/" ? "\\/" : character;
+    }
+    return escaped;
+}
+/**
+ * Whether the expression is one the `u` flag accepts, which is how a JSON Schema reader compiles it.
+ *
+ * **The flag is part of the contract, and leaving it off was the divergence.** A bare `/.../` makes
+ * `\p{L}` an identity escape for the letter `p`, so the expression the server ran was not the
+ * expression the spec author wrote. Measured against Ajv on the published document, with every
+ * verdict inverted:
+ *
+ * ```
+ * value        document (Ajv)   emitted validator
+ * "abc"        VALID            INVALID
+ * "Unicode"    VALID            INVALID
+ * "p{L}"       INVALID          VALID
+ * ```
+ *
+ * Ajv compiles a JSON Schema `pattern` with `u` by default, so carrying it here is not a rule laid
+ * on top of the contract; it is the contract.
+ *
+ * **Only when the pattern compiles under it.** `u` makes several ordinary spellings an error - a
+ * redundant `\-` outside a character class, a lone `]` or `{`, an identity escape such as `\a` - and
+ * 5 of 15 realistic patterns tested fail to compile with it. Those keep the bare form they already
+ * had, and {@link reportNonUnicodePattern} says so at build time, because a reader of the document
+ * cannot compile them either.
+ */
+export function unicodeSafe(pattern) {
+    try {
+        new RegExp(pattern, "u");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Warn when a `@pattern` is one a JSON Schema reader cannot compile at all.
+ *
+ * Separate from the `redos-prone-pattern` linter rule because the failure runs the other way: that
+ * one is about a pattern the validator runs too slowly, this one about a pattern nothing READING
+ * the document can run. And this one stays a diagnostic, because here the emitter cannot do what the
+ * spec asks: it falls back to a different expression from the one it publishes. Measured, Ajv on a published `^\-?\d+$`:
+ * `Invalid regular expression: /^\-?\d+$/u: Invalid escape`. The emitted validator falls back to the
+ * bare form and enforces it anyway, so the two artefacts stop agreeing without either one failing.
+ *
+ * De-duplicated per declaration through {@link firstReportOf}, which keys on the diagnostic as
+ * well as the declaration. Sharing one memo between the two warnings meant a declaration with
+ * both faults reported only whichever ran first.
+ */
+function reportNonUnicodePattern(program, pattern, target) {
+    if (unicodeSafe(pattern))
+        return;
+    if (!firstReportOf(program, "non-unicode-pattern", target))
+        return;
+    reportDiagnostic(program, { code: "non-unicode-pattern", format: { pattern }, target });
 }

package/dist/src/index.d.ts

@@ -8,3 +8,6 @@
  */
 export * from "./api.js";
 export { $onEmit } from "./emitter.js";
+export { $linter } from "./linter.js";
+export { redosPronePatternRule } from "./rules/redos-prone-pattern.rule.js";
+export { routeTemplateOf } from "./uri-template.js";

package/dist/src/index.js

@@ -8,3 +8,6 @@
  */
 export * from "./api.js";
 export { $onEmit } from "./emitter.js";
+export { $linter } from "./linter.js";
+export { redosPronePatternRule } from "./rules/redos-prone-pattern.rule.js";
+export { routeTemplateOf } from "./uri-template.js";