design: define initial regex matching and extraction contract

[vycdev2]

Summary

Define the initial regular-expression pattern, compilation, matching, extraction, Unicode, failure, resource, and source/runtime contract before adding the reserved but unimplemented regex standard-library module.

Source documentation

• docs/progress.md — Phase K: Full Standard Library
• docs/design.md — Standard Library
• docs/architecture.md — Phase K: Full Standard Library

Current state

The resolver recognizes regex as a builtin-module namespace, and the design describes it only as “pattern matching and extraction (when string functions aren't enough).” There are no regex.* signatures in the typechecker, no interpreter or runtime dispatch, no stdlib/regex.jett, no regex fixture coverage, and no regex-engine workspace dependency.

Consequently, no public API or behavior is selected yet. Pattern dialect and flags, one-shot versus compiled patterns, malformed-pattern errors, captures, no-match representation, Unicode behavior, replacement and splitting, resource limits, and the public-source/private-runtime boundary all remain undefined.

Scope

Decide and document:

• the initial public regex.* operations and types, including whether reusable compiled patterns are exposed;
• the supported pattern dialect, feature subset, flags, escaping, and portability guarantees;
• pattern-compilation timing and the canonical malformed-pattern error representation;
• whole-match/search behavior, no-match behavior, capture representation, named versus numbered captures, and unmatched optional groups;
• Unicode character classes, case folding, matching units, and any normalization policy;
• whether replacement and splitting belong in the initial slice and, if so, their capture expansion and empty-match behavior;
• resource and input/pattern-size limits, engine guarantees, and behavior for unsupported or expensive patterns;
• verify/comptime availability and deterministic behavior;
• the source-owned public .jett declarations and any private trusted engine kernels;
• compatibility and future-backend requirements without coupling the contract to one Rust engine accidentally.

Explicitly exclude implementation until this contract is selected, as well as glob syntax, parser pattern matching, and changes to Jett's existing language-level match constructs.

Acceptance criteria

• A design note selects the initial public functions/types and states which operations are deferred.
• The accepted pattern syntax, flags, unsupported constructs, and portability policy are explicit.
• Compilation, malformed-pattern, no-match, and capture behavior are specified with concrete result/error shapes.
• Unicode matching, case folding, normalization, and empty-match behavior are deliberate rather than inherited accidentally from an engine.
• Replacement/splitting scope and semantics are either specified or explicitly deferred.
• Resource-limit and unsupported/expensive-pattern behavior is documented.
• Verify/comptime behavior and deterministic guarantees are explicit.
• The source-owned public stdlib target, private trusted runtime-kernel boundary, and future-backend expectations are stated.
• Focused tests are planned for valid matching/extraction, invalid patterns, Unicode, captures, no-match, empty matches, and resource boundaries selected by the contract.
• docs/design.md, docs/architecture.md, and docs/progress.md link the selected contract and remain aligned.

Dependencies / open questions

The compiler-shipped module and trusted-origin model remains related to #3. The contract should not assume that the Rust regex crate, PCRE features, backtracking, grapheme semantics, or a reusable compiled-pattern value is canonical before those tradeoffs are decided.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.