package ecma-regex

Normative Hierarchy

This document fixes the governing-source hierarchy for ecma-regex.

It answers one question for each public surface:

which source governs this behavior first, which sources are secondary, and which parts are intentionally library-defined?

This file is not a test matrix and not a release log. It is the stable boundary that later conformance and evidence documents must use.

Source Precedence

When sources overlap, this repository uses the following precedence model.

1. ECMA-262 RegExp grammar and algorithms govern ECMAScript regular expression syntax, flags, literal parsing, matching, result shape, stateful lastIndex behavior, string-iterator behavior, and RegExp adapter semantics.
2. Unicode Character Database 16.0.0 governs the versioned data used for Unicode property names and values, script and script-extension membership, general categories, binary properties, character-set membership, and simple/common case folding.
3. ECMA-262 RegExp.escape governs the escaping helper exposed as Ecma_regex.escape and Ecma_regex.escape_js.
4. JSON Schema regex-facing behavior governs the consumer expectation that pattern and patternProperties are regular-expression searches, not implicit full-string matches. JSON Schema does not replace ECMA-262 as the RegExp semantic source.
5. The explicit OCaml API contract governs module layout, function names, OCaml result types, diagnostic-string error representation, and the choice to expose JavaScript-like operations as direct OCaml functions rather than through JavaScript object dispatch.

Corollaries:

• ECMA-262 RegExp semantics govern the regular-expression language and matcher.
• UCD 16.0.0 governs versioned Unicode facts consumed by the matcher.
• JSON Schema is a consumer profile over the same RegExp semantics.
• JavaScript object/prototype/constructor dispatch is not the governing model for this OCaml library's public API.

Architectural Hierarchy

The repository is expected to respect the following layered split.

Generated Facts

These are governed first by ECMA-262 tables and UCD 16.0.0 source data. They must come from generator tooling and generated runtime source, not from hand-maintained ad hoc runtime lists:

• Unicode property aliases and value aliases accepted by property escapes.
• Script and Script_Extensions membership.
• General_Category membership.
• Binary property membership.
• Character-class property membership.
• Character-set membership.
• Simple/common case folding data used by Unicode ignore-case matching.
• Runtime generated source needed by the library, such as lib/ecma_regex_ucd_tables.ml.

Generated cache or matrix outputs are development artifacts. They may be used to reproduce evidence, but they are not public API and are not part of the package surface.

Hand-Written Semantic Orchestration

These are governed by ECMA-262 grammar and algorithm prose and must remain explicit in runtime code:

• flag parsing and duplicate/unknown flag rejection;
• u / v conflict rejection;
• regular-expression literal parsing;
• compile-time syntax validation;
• matcher state and continuation behavior;
• captures, named captures, and backreferences;
• assertions, anchors, lookahead, and lookbehind;
• quantifier and alternation behavior;
• raw UTF-16 code-unit and code-point advancement;
• stateful lastIndex behavior;
• string iterator advancement after empty matches;
• RegExp adapter behavior for search, match, matchAll, split, replace, replaceAll, and escape.

Library-Defined Contract

These are intentionally outside direct normative text:

• OCaml module and function names.
• OCaml record and variant names.
• syntax_error = string as the current public diagnostic representation.
• Whether an operation returns option, list, result, or raises invalid_arg for inputs outside documented OCaml preconditions.
• The split between UTF-8 convenience APIs and explicit raw UTF-16 ECMAScript String APIs.
• The choice to expose JavaScript RegExp adapter semantics as direct functions instead of invoking JavaScript object/prototype protocol.
• Package documentation and install surface.

Library-defined does not mean untested. It means the behavior is judged by the documented OCaml contract and by consistency with the governing runtime semantics, not by one-to-one textual equivalence to a JavaScript host object operation.

Governing-Source Matrix

Product-Surface Boundary

ecma-regex is an OCaml library for ECMAScript regular-expression behavior. It is not a JavaScript runtime.

The following JavaScript-host behaviors are outside this public surface:

• JavaScript object dispatch;
• constructors and subclassing;
• prototype mutation;
• dynamic method lookup;
• function objects and function metadata;
• functional replacer dispatch as a JavaScript callable;
• JavaScript receiver coercion and object wrapping.

These areas are not runtime matcher semantics. They are JavaScript host/object protocol. The OCaml library may expose equivalent RegExp operations as direct functions, and those direct functions are the public surface to test.

Any future claim that one of these excluded areas is required must show:

1. the ECMA-262 requirement is actually RegExp semantic behavior rather than JavaScript object protocol;
2. the behavior cannot already be expressed by the explicit OCaml API;
3. the public API change needed to expose it;
4. the tests that will prove it.

Until then, these areas belong in product-surface policy or a deviation register as non-OCaml-surface behavior, not in the implementation backlog.

Consumer-Profile Boundary

JSON Schema compatibility is a consumer profile over ECMA-262 RegExp semantics.

For this repository:

• JSON Schema pattern and patternProperties use search semantics, not implicit full-string anchoring.
• format: regex is a compile/parse consumer of the same RegExp syntax.
• JSON Schema does not introduce a different regular-expression engine.
• JSON Schema corpus evidence can prove consumer compatibility, but ECMA-262 remains the governing source for regexp syntax and matching semantics.

Unicode Version Boundary

Unicode-sensitive behavior in this repository is pinned to UCD 16.0.0.

This affects:

• Unicode property escapes;
• script and script-extension membership;
• general category membership;
• binary properties;
• UnicodeSets character-class behavior;
• simple/common case folding used by Unicode ignore-case matching.

Changing the Unicode version is a semantic change. It requires regenerated runtime source and regenerated evidence, followed by the relevant test gates.

Decision Gate

Any implementation or documentation change should be able to name:

1. the governing source from this hierarchy;
2. the public surface affected;
3. whether the behavior is normative, contract-only, library-defined, or outside the product API;
4. the tests or evidence that prove the behavior;
5. whether generated facts or hand-written semantic orchestration are involved.

If one of these is missing, the work stays in research/audit phase and must not be described as completed release work.