@astrale-os/kernel-dsl 0.2.0-beta.9 → 1.0.0-beta.2

package/dist/v1/language/value/model/blob.d.ts

@@ -0,0 +1,31 @@
+import type { JsonSchemaObject } from './schema.js';
+declare const BLOB_SCHEMA: unique symbol;
+/** The portable value read from a blob-kind Node property. */
+export interface BlobRef {
+    readonly digest: `sha256:${string}`;
+    readonly mediaType: string;
+    readonly size: number;
+}
+/** An uploader-bound receipt is the only ordinary write input for a blob property. */
+export type BlobReceipt = string & {
+    readonly __brand: 'BlobReceipt';
+};
+/** Type-only marker; the serialized schema remains ordinary JSON. */
+export interface BlobSchema extends JsonSchemaObject {
+    readonly [BLOB_SCHEMA]: true;
+}
+export interface BlobOptions {
+    /** Required property-level bound, in bytes. */
+    readonly maxBytes: number;
+    /** Omission admits any canonical artifact media type. */
+    readonly mediaTypes?: readonly string[];
+}
+export declare const BLOB_VALUE_KIND: 'blob';
+/** Build the one canonical V1 schema shape for a blob-valued Node property. */
+export declare function blob(options: BlobOptions): BlobSchema;
+/** Marker recognition on an already admitted V1 value schema. */
+export declare function isBlobValueSchema(input: unknown): input is BlobSchema;
+/** Exact canonical artifact media type, including ordered token parameters. */
+export declare function canonicalMediaType(input: string): string;
+export declare function isCanonicalBlobRef(input: unknown): input is BlobRef;
+export {};

package/dist/v1/language/value/model/blob.js

@@ -0,0 +1,90 @@
+export const BLOB_VALUE_KIND = 'blob';
+const BLOB_DIGEST_PATTERN = 'sha256:[0-9a-f]{64}';
+const BLOB_MEDIA_TYPE_PATTERN = "[a-z0-9!#$%&'*+.^_`|~-]+/[a-z0-9!#$%&'*+.^_`|~-]+(;[a-z0-9!#$%&'*+.^_`|~-]+=[!#$%&'*+.^_`|~0-9A-Za-z-]+)*";
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+/** Build the one canonical V1 schema shape for a blob-valued Node property. */
+export function blob(options) {
+    if (!Number.isSafeInteger(options?.maxBytes) || options.maxBytes < 1) {
+        throw new TypeError('Blob maxBytes must be a positive safe integer.');
+    }
+    let mediaTypes;
+    if (options.mediaTypes !== undefined) {
+        if (!Array.isArray(options.mediaTypes) || options.mediaTypes.length === 0) {
+            throw new TypeError('Blob mediaTypes must be a non-empty list.');
+        }
+        mediaTypes = [...new Set(options.mediaTypes.map(canonicalMediaType))].sort();
+    }
+    return Object.freeze({
+        type: 'object',
+        'x-astrale-value-kind': BLOB_VALUE_KIND,
+        properties: {
+            digest: { type: 'string', fullMatch: BLOB_DIGEST_PATTERN },
+            mediaType: mediaTypes === undefined
+                ? { type: 'string', fullMatch: BLOB_MEDIA_TYPE_PATTERN }
+                : { enum: mediaTypes },
+            size: { type: 'integer', minimum: 0, maximum: options.maxBytes },
+        },
+        required: ['digest', 'mediaType', 'size'],
+        additionalProperties: false,
+    });
+}
+/** Marker recognition on an already admitted V1 value schema. */
+export function isBlobValueSchema(input) {
+    return (input !== null &&
+        typeof input === 'object' &&
+        !Array.isArray(input) &&
+        input['x-astrale-value-kind'] === BLOB_VALUE_KIND);
+}
+/** Exact canonical artifact media type, including ordered token parameters. */
+export function canonicalMediaType(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('Blob media type is invalid.');
+    const [essence, ...parametersInput] = input.split(';');
+    const [rawType, rawSubtype, ...extra] = essence.trim().split('/');
+    if (rawType === undefined ||
+        rawSubtype === undefined ||
+        extra.length !== 0 ||
+        !TOKEN.test(rawType) ||
+        !TOKEN.test(rawSubtype)) {
+        throw new TypeError('Blob media type is invalid.');
+    }
+    const parameters = parametersInput.map((part) => {
+        const separator = part.indexOf('=');
+        if (separator <= 0)
+            throw new TypeError('Blob media type parameter is invalid.');
+        const name = part.slice(0, separator).trim().toLowerCase();
+        const value = part.slice(separator + 1).trim();
+        if (!TOKEN.test(name) || !TOKEN.test(value)) {
+            throw new TypeError('Blob media type parameter is invalid.');
+        }
+        return [name, value];
+    });
+    parameters.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    if (new Set(parameters.map(([name]) => name)).size !== parameters.length) {
+        throw new TypeError('Blob media type parameters are duplicated.');
+    }
+    return parameters.reduce((result, [name, value]) => `${result};${name}=${value}`, `${rawType.toLowerCase()}/${rawSubtype.toLowerCase()}`);
+}
+export function isCanonicalBlobRef(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return false;
+    const value = input;
+    if (Object.keys(value).length !== 3 ||
+        !Object.hasOwn(value, 'digest') ||
+        !Object.hasOwn(value, 'mediaType') ||
+        !Object.hasOwn(value, 'size') ||
+        typeof value.digest !== 'string' ||
+        !DIGEST.test(value.digest) ||
+        typeof value.mediaType !== 'string' ||
+        !Number.isSafeInteger(value.size) ||
+        value.size < 0) {
+        return false;
+    }
+    try {
+        return canonicalMediaType(value.mediaType) === value.mediaType;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/v1/language/value/model/instant.d.ts

@@ -1,6 +1,4 @@
 /** Exact portable UTC millisecond Instant used by the V1 value-schema dialect. */
-/** Canonical value-language annotation for an Instant string. */
-export declare const INSTANT_VALUE_KIND: 'instant';
 export declare const instant: Readonly<{
     readonly type: 'string';
     readonly 'x-astrale-value-kind': 'instant';

package/dist/v1/language/value/model/instant.js

@@ -1,6 +1,6 @@
 /** Exact portable UTC millisecond Instant used by the V1 value-schema dialect. */
 /** Canonical value-language annotation for an Instant string. */
-export const INSTANT_VALUE_KIND = 'instant';
+const INSTANT_VALUE_KIND = 'instant';
 export const instant = Object.freeze({
     type: 'string',
     'x-astrale-value-kind': INSTANT_VALUE_KIND,

package/dist/v1/language/value/model/schema.d.ts

@@ -21,5 +21,6 @@ export interface PathAnnotation {
     readonly cardinality: 'one';
     readonly accepts: readonly ClassRef[];
 }
-export declare const VALUE_SCHEMA_CONTEXTS: readonly ['property-facet', 'callable-input', 'callable-output'];
+declare const VALUE_SCHEMA_CONTEXTS: readonly ['property-facet', 'callable-input', 'callable-output'];
 export type ValueSchemaContext = (typeof VALUE_SCHEMA_CONTEXTS)[number];
+export {};

package/dist/v1/language/value/model/schema.js

@@ -4,8 +4,4 @@ export const JSON_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema
 export const VALUE_SCHEMA_DIALECT = 'https://schemas.astrale.ai/dsl/v1/value-schema';
 /** Required vocabulary carried by the V1 value-schema dialect. */
 export const VALUE_SCHEMA_VOCABULARY = 'https://schemas.astrale.ai/dsl/v1/value-schema/vocabulary';
-export const VALUE_SCHEMA_CONTEXTS = [
-    'property-facet',
-    'callable-input',
-    'callable-output',
-];
+const VALUE_SCHEMA_CONTEXTS = ['property-facet', 'callable-input', 'callable-output'];

package/dist/v1/language/value/ordering.d.ts

@@ -1,4 +1,5 @@
 import type { ValueProgram } from './compile/model.js';
+import type { CompiledInstanceSchema } from './evaluate/types.js';
 import type { JsonSchema } from './model/schema.js';
 import type { ValueSchemaRegistry } from './reference/registry.js';
 export type OrderingKind = 'boolean' | 'number' | 'string' | 'instant';
@@ -11,3 +12,4 @@ export type OrderingKind = 'boolean' | 'number' | 'string' | 'instant';
 export declare function classifyOrdering(contract: JsonSchema, registry: ValueSchemaRegistry): OrderingKind | undefined;
 /** Recompute the scalar ordering classification from one admitted portable value program. */
 export declare function classifyValueProgramOrdering(program: ValueProgram): OrderingKind | undefined;
+export declare function classifyPreparedOrdering(compiled: CompiledInstanceSchema): OrderingKind | undefined;

package/dist/v1/language/value/ordering.js

@@ -18,17 +18,13 @@ export function classifyOrdering(contract, registry) {
     const prepared = prepareValueSchema(contract, registry, '');
     if (!prepared.compiled)
         return undefined;
-    const candidates = new OrderingClassifier(prepared.value).classify(prepared.value.root);
-    if (candidates.size !== 1)
-        return undefined;
-    const [kind] = candidates;
-    return kind === 'boolean' || kind === 'number' || kind === 'string' || kind === 'instant'
-        ? kind
-        : undefined;
+    return classifyPreparedOrdering(prepared.value);
 }
 /** Recompute the scalar ordering classification from one admitted portable value program. */
 export function classifyValueProgramOrdering(program) {
-    const compiled = loadValueProgram(program);
+    return classifyPreparedOrdering(loadValueProgram(program));
+}
+export function classifyPreparedOrdering(compiled) {
     const candidates = new OrderingClassifier(compiled).classify(compiled.root);
     if (candidates.size !== 1)
         return undefined;

package/dist/v1/language/value/profile/json.validate.js

@@ -1,4 +1,4 @@
-import { accept as acceptJsonValue, BoundaryError as JsonBoundaryError, } from '@astrale-os/kernel-dsl/value';
+import { acceptForRead as acceptJsonValue, BoundaryError as JsonBoundaryError, } from '@astrale-os/kernel-dsl/value';
 import { diagnostic } from '../../validation/diagnostic.js';
 export function validateCanonicalJsonDomain(value, pointer) {
     try {

package/dist/v1/language/value/profile/rules.js

@@ -1,8 +1,9 @@
 import { json } from '@astrale-os/kernel-dsl/value';
 import { diagnostic } from '../../validation/diagnostic.js';
+import { blob, BLOB_VALUE_KIND } from '../model/blob.js';
 import { isValueObject as isJsonObject } from '../model/object.js';
 import { VALUE_SCHEMA_DIALECT } from '../model/schema.js';
-import { isIRegexp } from '../regexp/syntax.js';
+import { refuseIRegexp, stateBudgetMessage } from '../regexp/syntax.js';
 import { walkSchema } from '../syntax/walk.js';
 import { FORBIDDEN_DYNAMIC_KEYWORDS, STANDARD_SCHEMA_KEYWORDS } from './vocabulary.js';
 export function validateSchemaProfile(schema, context, pointer) {
@@ -28,19 +29,50 @@ export function validateSchemaProfile(schema, context, pointer) {
             diagnostics.push(diagnostic('VS_RESOURCE_ID', `${currentPointer}/$id`, '$id is forbidden in an embedded V1 value schema.'));
         }
         validateSemanticSets(location.schema, currentPointer, diagnostics);
-        validateValueKind(location.schema, currentPointer, diagnostics);
+        validateValueKind(location.schema, context, location.depth, currentPointer, diagnostics);
         validateRegexes(location.schema, currentPointer, diagnostics);
     });
-    void context;
     return diagnostics;
 }
-function validateValueKind(schema, pointer, diagnostics) {
+function validateValueKind(schema, context, depth, pointer, diagnostics) {
     if (!Object.hasOwn(schema, 'x-astrale-value-kind'))
         return;
-    if (schema['x-astrale-value-kind'] !== 'instant' || schema.type !== 'string') {
+    if (schema['x-astrale-value-kind'] === BLOB_VALUE_KIND) {
+        if (context !== 'property-facet' || depth !== 0 || !isCanonicalBlobSchema(schema)) {
+            diagnostics.push(diagnostic('VS_VALUE_KIND', `${pointer}/x-astrale-value-kind`, 'blob must be the exact schema.values.blob output at the root of a Node property.'));
+        }
+    }
+    else if (schema['x-astrale-value-kind'] !== 'instant' || schema.type !== 'string') {
         diagnostics.push(diagnostic('VS_VALUE_KIND', `${pointer}/x-astrale-value-kind`, 'x-astrale-value-kind is exactly instant and requires type string at the same schema location.'));
     }
 }
+function isCanonicalBlobSchema(input) {
+    const properties = input.properties;
+    if (!isJsonObject(properties))
+        return false;
+    const size = properties.size;
+    const mediaType = properties.mediaType;
+    if (!isJsonObject(size) || !isJsonObject(mediaType))
+        return false;
+    const maxBytes = size.maximum;
+    if (typeof maxBytes !== 'number' || !Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        return false;
+    }
+    const mediaTypes = mediaType.enum;
+    if (mediaTypes !== undefined && (!Array.isArray(mediaTypes) || !mediaTypes.every(isString))) {
+        return false;
+    }
+    try {
+        return (json.serialize(input) ===
+            json.serialize(blob({ maxBytes, ...(mediaTypes === undefined ? {} : { mediaTypes }) })));
+    }
+    catch {
+        return false;
+    }
+}
+function isString(input) {
+    return typeof input === 'string';
+}
 function validateSemanticSets(schema, pointer, diagnostics) {
     if (Array.isArray(schema.type)) {
         rejectPrimitiveDuplicates(schema.type, `${pointer}/type`, 'type', diagnostics);
@@ -63,20 +95,24 @@ function validateRegexes(schema, pointer, diagnostics) {
     if (Object.hasOwn(schema, 'fullMatch') && typeof schema.fullMatch !== 'string') {
         diagnostics.push(diagnostic('VS_META_SCHEMA', `${pointer}/fullMatch`, 'fullMatch must be an I-Regexp source string.'));
     }
-    if (typeof schema.fullMatch === 'string' && !isIRegexp(schema.fullMatch)) {
-        diagnostics.push(diagnostic('VS_REGEX_PORTABLE', `${pointer}/fullMatch`, 'fullMatch must satisfy the complete RFC 9485 I-Regexp syntax.'));
+    if (typeof schema.fullMatch === 'string') {
+        portableRegex(schema.fullMatch, `${pointer}/fullMatch`, 'fullMatch', 'fullMatch must satisfy the complete RFC 9485 I-Regexp syntax.', diagnostics);
     }
-    if (typeof schema.pattern === 'string' && !isIRegexp(schema.pattern)) {
-        diagnostics.push(diagnostic('VS_REGEX_PORTABLE', `${pointer}/pattern`, 'pattern must satisfy the complete RFC 9485 I-Regexp syntax.'));
+    if (typeof schema.pattern === 'string') {
+        portableRegex(schema.pattern, `${pointer}/pattern`, 'pattern', 'pattern must satisfy the complete RFC 9485 I-Regexp syntax.', diagnostics);
     }
     if (isJsonObject(schema.patternProperties)) {
         for (const pattern of Object.keys(schema.patternProperties)) {
-            if (!isIRegexp(pattern)) {
-                diagnostics.push(diagnostic('VS_REGEX_PORTABLE', `${pointer}/patternProperties/${escapeToken(pattern)}`, 'patternProperties keys must satisfy RFC 9485 I-Regexp syntax.'));
-            }
+            portableRegex(pattern, `${pointer}/patternProperties/${escapeToken(pattern)}`, 'A patternProperties key', 'patternProperties keys must satisfy RFC 9485 I-Regexp syntax.', diagnostics);
         }
     }
 }
+function portableRegex(source, pointer, subject, syntax, diagnostics) {
+    const refusal = refuseIRegexp(source);
+    if (refusal === undefined)
+        return;
+    diagnostics.push(diagnostic('VS_REGEX_PORTABLE', pointer, refusal === 'syntax' ? syntax : stateBudgetMessage(subject)));
+}
 function rejectPrimitiveDuplicates(values, pointer, name, diagnostics) {
     const seen = new Set();
     for (const value of values) {

package/dist/v1/language/value/reference/registry.d.ts

@@ -1,6 +1,6 @@
 import type { ClassRef } from '../../../addressing/index.js';
 import type { JsonSchema } from '../model/schema.js';
-export interface ValueSchemaDependency {
+interface ValueSchemaDependency {
     readonly origin: string;
     readonly revision: `sha256:${string}`;
 }
@@ -22,3 +22,4 @@ export interface ValueSchemaRegistry {
     readonly transitiveDependencies: readonly ValueSchemaDomainRegistry[];
     readonly graphNodePath: JsonSchema;
 }
+export {};

package/dist/v1/language/value/regexp/ast.js

@@ -1,11 +1,8 @@
-const CATEGORY = /^(?:L[lmotu]?|M[cen]?|N[dlo]?|P[cdfios]?|Z[lps]?|S[ckmo]?|C[cfno]?)$/u;
+import { categoryRanges, complement, mergeRanges } from './unicode.js';
+const CATEGORY = /^(?:L[lmotu]?|M[cen]?|N[dlo]?|P[cdefios]?|Z[lps]?|S[ckmo]?|C[cfno]?)$/u;
 const MAX_CODE_POINTS = 4096;
 const MAX_NESTING = 32;
 const MAX_REPEAT = 1000;
-const SCALAR_RANGES = [
-    [0, 0xd7ff],
-    [0xe000, 0x10ffff],
-];
 const DOT_RANGES = [
     [0, 9],
     [11, 12],
@@ -200,7 +197,7 @@ class Parser {
         if (this.peek() !== '\\')
             return undefined;
         const escaped = this.peek(1);
-        if (escaped === undefined || !'()*+-.?[\\]^nrt{}'.includes(escaped))
+        if (escaped === undefined || !'()*+-.?[\\]^nrt{|}'.includes(escaped))
             return undefined;
         this.index += 2;
         const value = escaped === 'n' ? '\n' : escaped === 'r' ? '\r' : escaped === 't' ? '\t' : escaped;
@@ -237,68 +234,10 @@ class Parser {
         return this.characters[this.index + offset];
     }
 }
-const categories = new Map();
-function categoryRanges(category) {
-    const retained = categories.get(category);
-    if (retained !== undefined)
-        return retained;
-    const expression = new RegExp(`^\\p{${category}}$`, 'u');
-    const output = [];
-    let start;
-    let previous = -2;
-    for (const [minimum, maximum] of SCALAR_RANGES) {
-        for (let scalar = minimum; scalar <= maximum; scalar++) {
-            if (!expression.test(String.fromCodePoint(scalar)))
-                continue;
-            if (start === undefined)
-                start = scalar;
-            else if (scalar !== previous + 1) {
-                output.push([start, previous]);
-                start = scalar;
-            }
-            previous = scalar;
-        }
-    }
-    if (start !== undefined)
-        output.push([start, previous]);
-    const frozen = Object.freeze(output.map((range) => Object.freeze(range)));
-    categories.set(category, frozen);
-    return frozen;
-}
 function singleton(value) {
     const scalar = value.codePointAt(0);
     return scalar === undefined ? [] : [[scalar, scalar]];
 }
-function mergeRanges(input) {
-    const sorted = [...input].sort((left, right) => left[0] - right[0] || left[1] - right[1]);
-    const output = [];
-    for (const range of sorted) {
-        const previous = output.at(-1);
-        if (previous === undefined || range[0] > previous[1] + 1)
-            output.push([range[0], range[1]]);
-        else
-            output[output.length - 1] = [previous[0], Math.max(previous[1], range[1])];
-    }
-    return output;
-}
-function complement(input) {
-    const output = [];
-    for (const [minimum, maximum] of SCALAR_RANGES) {
-        let cursor = minimum;
-        for (const [start, end] of input) {
-            if (end < minimum || start > maximum)
-                continue;
-            if (start > cursor)
-                output.push([cursor, Math.min(start - 1, maximum)]);
-            cursor = Math.max(cursor, end + 1);
-            if (cursor > maximum)
-                break;
-        }
-        if (cursor <= maximum)
-            output.push([cursor, maximum]);
-    }
-    return output;
-}
 function isNormalCharacter(value) {
     const code = value.codePointAt(0);
     return (code !== undefined &&

package/dist/v1/language/value/regexp/compile.d.ts

@@ -1,3 +1,32 @@
-import type { Pattern } from '../compile/model.js';
-/** Compile one admitted I-Regexp AST to portable Thompson-NFA data. */
-export declare function compilePattern(source: string): Pattern;
+import type { Pattern, RunPattern } from '../compile/model.js';
+import type { Expression } from './ast.js';
+/**
+ * The most states the machine of one I-Regexp may have (`limits.regexp.maxStates`), an
+ * implementation limit as RFC 9485 §8 allows. Counted repetitions are expanded copy by copy, so the
+ * parser's bounds on length, nesting and counts alone admit machines of billions of states. The
+ * counted-run form never expands, so it is not subject to this budget.
+ */
+export declare const MAX_STATES = 10000;
+/**
+ * Thrown when an I-Regexp source compiles to a machine of more than `MAX_STATES` states. A short
+ * branching source such as `(a{0,1000}){0,60}b` would unroll to ~120k states and cost seconds per
+ * validated value (P1-I-01); it is refused before any state is built.
+ */
+export declare class PatternComplexityError extends RangeError {
+    readonly limit: number;
+    constructor(limit?: number);
+}
+/** Compile scalar sequences as counted runs; preserve the NFA for branching expressions. */
+export declare function compilePattern(source: string): Pattern | RunPattern;
+/**
+ * Whether a parsed I-Regexp compiles within the state budget: as counted runs, which never expand,
+ * or as a machine of at most `MAX_STATES` states, counted from the AST before anything is built.
+ */
+export declare function withinStateBudget(expression: Expression): boolean;
+/**
+ * The number of states `Builder` builds for an expression, computed from the AST alone: `states`
+ * in `proofs/Regexp.lean`, where `compile_size` proves it exact. Nesting and counts are bounded by
+ * the parser, so the count stays finite; it is exact up to `Number.MAX_SAFE_INTEGER`, and above it
+ * every rounding keeps it above the budget.
+ */
+export declare function states(expression: Expression): number;

package/dist/v1/language/value/regexp/compile.js

@@ -1,9 +1,34 @@
 import { parseIRegexp } from './ast.js';
-/** Compile one admitted I-Regexp AST to portable Thompson-NFA data. */
+/**
+ * The most states the machine of one I-Regexp may have (`limits.regexp.maxStates`), an
+ * implementation limit as RFC 9485 §8 allows. Counted repetitions are expanded copy by copy, so the
+ * parser's bounds on length, nesting and counts alone admit machines of billions of states. The
+ * counted-run form never expands, so it is not subject to this budget.
+ */
+export const MAX_STATES = 10_000;
+/**
+ * Thrown when an I-Regexp source compiles to a machine of more than `MAX_STATES` states. A short
+ * branching source such as `(a{0,1000}){0,60}b` would unroll to ~120k states and cost seconds per
+ * validated value (P1-I-01); it is refused before any state is built.
+ */
+export class PatternComplexityError extends RangeError {
+    limit;
+    constructor(limit = MAX_STATES) {
+        super(`Cannot compile an I-Regexp machine of more than ${limit} states.`);
+        this.limit = limit;
+        this.name = 'PatternComplexityError';
+    }
+}
+/** Compile scalar sequences as counted runs; preserve the NFA for branching expressions. */
 export function compilePattern(source) {
     const expression = parseIRegexp(source);
     if (expression === undefined)
         throw new TypeError('Cannot compile an invalid I-Regexp source.');
+    const runs = scalarRuns(expression);
+    if (runs !== undefined)
+        return Object.freeze({ source, runs });
+    if (states(expression) > MAX_STATES)
+        throw new PatternComplexityError();
     const builder = new Builder();
     const fragment = builder.expression(expression);
     builder.states[fragment.end].accepting = true;
@@ -13,9 +38,77 @@ export function compilePattern(source) {
         states: Object.freeze(builder.states.map(freezeState)),
     });
 }
+/**
+ * Whether a parsed I-Regexp compiles within the state budget: as counted runs, which never expand,
+ * or as a machine of at most `MAX_STATES` states, counted from the AST before anything is built.
+ */
+export function withinStateBudget(expression) {
+    return scalarRuns(expression) !== undefined || states(expression) <= MAX_STATES;
+}
+/**
+ * The number of states `Builder` builds for an expression, computed from the AST alone: `states`
+ * in `proofs/Regexp.lean`, where `compile_size` proves it exact. Nesting and counts are bounded by
+ * the parser, so the count stays finite; it is exact up to `Number.MAX_SAFE_INTEGER`, and above it
+ * every rounding keeps it above the budget.
+ */
+export function states(expression) {
+    const [only, ...others] = expression.alternatives;
+    if (only !== undefined && others.length === 0)
+        return sequenceStates(only);
+    return expression.alternatives.reduce((total, sequence) => total + sequenceStates(sequence), 2);
+}
+function sequenceStates({ pieces }) {
+    if (pieces.length === 0)
+        return 2;
+    return pieces.reduce((total, piece) => total + pieceStates(piece), 0);
+}
+/** `pieceStates`: `minimum` copies, then a star, or a shared end and the optional copies. */
+function pieceStates({ atom, minimum, maximum }) {
+    const copy = atom.kind === 'ranges' ? 2 : states(atom.expression);
+    if (maximum === undefined)
+        return minimum * copy + (copy + 2);
+    return ((minimum === 0 ? 2 : minimum * copy) +
+        (maximum === minimum ? 0 : 1 + (maximum - minimum) * copy));
+}
+function scalarRuns(expression) {
+    if (expression.alternatives.length !== 1)
+        return undefined;
+    const pieces = expression.alternatives[0].pieces;
+    let counted = false;
+    for (let index = 0; index < pieces.length; index++) {
+        const piece = pieces[index];
+        if (piece.atom.kind !== 'ranges' ||
+            (index !== pieces.length - 1 && piece.minimum !== piece.maximum))
+            return undefined;
+        if (piece.maximum !== undefined && piece.maximum > 1)
+            counted = true;
+    }
+    if (!counted)
+        return undefined;
+    const runs = [];
+    for (const piece of pieces) {
+        if (piece.atom.kind !== 'ranges')
+            return undefined;
+        runs.push(Object.freeze({
+            ranges: freezeRanges(piece.atom.ranges),
+            minimum: piece.minimum,
+            ...(piece.maximum === undefined ? {} : { maximum: piece.maximum }),
+        }));
+    }
+    return Object.freeze(runs);
+}
+function freezeRanges(ranges) {
+    if (Object.isFrozen(ranges))
+        return ranges;
+    for (const range of ranges)
+        Object.freeze(range);
+    return Object.freeze(ranges);
+}
 class Builder {
     states = [];
     expression(expression) {
+        if (expression.alternatives.length === 1)
+            return this.sequence(expression.alternatives[0]);
         const start = this.state();
         const end = this.state();
         for (const alternative of expression.alternatives) {
@@ -26,22 +119,34 @@ class Builder {
         return { start, end };
     }
     sequence(sequence) {
-        let output = this.empty();
-        for (const piece of sequence.pieces)
-            output = this.concat(output, this.piece(piece));
-        return output;
+        let output;
+        for (const piece of sequence.pieces) {
+            const fragment = this.piece(piece);
+            output = output === undefined ? fragment : this.concat(output, fragment);
+        }
+        return output ?? this.empty();
     }
     piece(piece) {
-        let output = this.empty();
+        let output;
         for (let index = 0; index < piece.minimum; index++) {
-            output = this.concat(output, this.atom(piece.atom));
+            const fragment = this.atom(piece.atom);
+            output = output === undefined ? fragment : this.concat(output, fragment);
         }
-        if (piece.maximum === undefined)
-            return this.concat(output, this.star(piece.atom));
+        if (piece.maximum === undefined) {
+            const repeated = this.star(piece.atom);
+            return output === undefined ? repeated : this.concat(output, repeated);
+        }
+        if (piece.maximum === piece.minimum)
+            return output ?? this.empty();
+        output ??= this.empty();
+        const end = this.state();
         for (let index = piece.minimum; index < piece.maximum; index++) {
-            output = this.concat(output, this.optional(piece.atom));
+            // A shorter repetition exits the whole suffix, rather than skipping arbitrary copies.
+            this.epsilon(output.end, end);
+            output = this.concat(output, this.atom(piece.atom));
         }
-        return output;
+        this.epsilon(output.end, end);
+        return { start: output.start, end };
     }
     atom(atom) {
         if (atom.kind === 'expression')
@@ -51,15 +156,6 @@ class Builder {
         this.states[start].transitions.push({ to: end, ranges: atom.ranges });
         return { start, end };
     }
-    optional(atom) {
-        const start = this.state();
-        const end = this.state();
-        const child = this.atom(atom);
-        this.epsilon(start, end);
-        this.epsilon(start, child.start);
-        this.epsilon(child.end, end);
-        return { start, end };
-    }
     star(atom) {
         const start = this.state();
         const end = this.state();
@@ -90,7 +186,7 @@ class Builder {
 function freezeState(state) {
     return Object.freeze({
         epsilon: Object.freeze(state.epsilon),
-        transitions: Object.freeze(state.transitions.map((transition) => Object.freeze({ to: transition.to, ranges: Object.freeze(transition.ranges) }))),
+        transitions: Object.freeze(state.transitions.map((transition) => Object.freeze({ to: transition.to, ranges: freezeRanges(transition.ranges) }))),
         ...(state.accepting === true ? { accepting: true } : {}),
     });
 }

package/dist/v1/language/value/regexp/matcher.d.ts

@@ -1,7 +1,10 @@
-import type { Pattern } from '../compile/model.js';
+import type { Pattern, RunPattern } from '../compile/model.js';
 export interface IRegexpMatcher {
     test(value: string): boolean;
     matches(value: string): boolean;
 }
-/** Load portable NFA data without a regex engine or dynamic compilation. */
-export declare function loadPattern(pattern: Pattern): IRegexpMatcher;
+/**
+ * Load the portable counted-run or Thompson NFA executor for search and whole-string matching.
+ * Scratch belongs to one invocation: no match-result cache, shared mutable cursor or DFA expansion.
+ */
+export declare function loadPattern(pattern: Pattern | RunPattern): IRegexpMatcher;