AEOS Pattern Profile v1

Status: implementation-ahead appendix for consolidated v1

Canonical topic owners: ../AEOS-spec-v1.md, ../contracts/

This appendix describes a pattern DSL that is ahead of the currently locked AEOS v1 baseline. It is informative for future work and must not be treated as required for AEON Core v1 or the shipped AEOS v1 baseline.

1. Scope and purpose

AEOS Pattern Profile v1 defines a form-only constraint language for validating StringLiteral values emitted by AEON Core.

Goals:

• deterministic cross-language behavior (Go/Rust/TS)
• explicit, auditable constraints (no opaque regex)
• stable CTS semantics
• strict separation between form (AEOS) and meaning (processors)

2. Applicability

Patterns in this profile MAY be applied only to the decoded string value of a StringLiteral emitted by AEON Core.

If a pattern is applied to any non-StringLiteral value, the validator MUST emit:

• code = "constraint_inapplicable"
• phase = "schema_validation"
• path = <data rule path>
• span = <data value span>

3. Canonical syntax requirements

3.1 Explicit assignment only

All normative structures MUST use explicit AEON assignment syntax:

key = { ... }

key = "value"

key = 123

• ❌ container shorthand MUST NOT be used in normative examples

3.2 Pattern Object

A Pattern Object has the form:

Rules:

• pattern MUST be an object.
• pattern MUST contain exactly one node-type key.
• If pattern contains zero or more than one node-type key:

• schema error code = "invalid_pattern_shape"

Normative clarification: A pattern = { … } wrapper is required only at pattern definition boundaries (e.g., in schema.patterns). Nested pattern composition uses Node Objects directly (e.g., inside all, any, apply, each) and MUST NOT use pattern = {} again.

4. Node types (v1)

Defined node-type keys:

• all
• any
• not
• pred
• split
• labels

Unknown node-type key:

• schema error code = "unknown_pattern_node"

5. Node definitions

5.1 Common rule: “Node Object” (for clauses)

A Node Object is an object that contains exactly one node-type key (from §4), for example:

If a Node Object contains zero or more than one node-type key:

• schema error code = "invalid_node_object_shape"

This rule is used for:

• clauses under all/any
• the wrapped node under not
• nested nodes inside apply / each

5.2 all

Shape

Rules:

• all MUST be an object.
• all MUST contain one or more entries.
• Each entry value MUST be a Node Object (see §5.1).

Invalid:

• schema error code = "invalid_all_clause_shape"

Semantics

• Evaluate entries in lexical order as written in AEON source.
• all passes iff all clauses pass.
• MAY short-circuit on first failure.

5.3 any

Shape

Rules:

• any MUST be an object.
• any MUST contain one or more entries.
• Each entry value MUST be a Node Object.

Invalid:

• schema error code = "invalid_any_clause_shape"

Semantics

• Evaluate in lexical order.
• any passes iff at least one clause passes.
• MAY short-circuit on first success.

5.4 not (unary)

Shape

Rules:

• not MUST be an object.
• not MUST itself be a Node Object (i.e. contain exactly one node-type key).

• This means not wraps exactly one node.

Invalid:

• schema error code = "invalid_not_shape"

Semantics

• Evaluate the wrapped node.
• not passes iff the wrapped node fails.

5.5 pred (primitive predicates)

Shape

Rules:

• pred MUST be an object.
• pred MUST contain exactly one predicate-kind key.
• Unknown predicate-kind:

• schema error code = "unknown_predicate_kind"

Predicate kinds (v1)

5.5.1 length

Rules:

• value MUST be an object.
• min and max optional.
• if present, MUST be non-negative integers.
• if both present, MUST satisfy min <= max.

Invalid:

• schema error code = "invalid_length_predicate"

Semantics:

• length measured in Unicode code points (decoded string, no normalization).

Fail on data:

• runtime code length_violation

5.5.2 contains

Rules:

• value MUST be a string.

Invalid:

• schema error invalid_contains_predicate

Fail on data:

• runtime code predicate_violation

5.5.3 starts_with

Rules:

• value MUST be a string.

Invalid:

• schema error invalid_starts_with_predicate

Fail on data:

• runtime code predicate_violation

5.5.4 ends_with

Rules:

• value MUST be a string.

Invalid:

• schema error invalid_ends_with_predicate

Fail on data:

• runtime code predicate_violation

5.5.5 no_whitespace

Rules:

• value MUST be boolean.

Invalid:

• schema error invalid_no_whitespace_predicate

Semantics (v1 whitespace set):

• forbidden code points are exactly:

• U+0009 TAB
• U+000A LF
• U+000D CR
• U+0020 SPACE

Fail on data:

• runtime code whitespace_forbidden

5.5.6 charset

Rules:

• value MUST be a string naming a charset in the registry (see §6).

Invalid:

• schema error unknown_charset

Fail on data:

• runtime code charset_violation

5.6 split (index-safe REQUIRED)

Shape (REQUIRED)

Rules:

• split MUST be an object.
• sep MUST be a non-empty string.
• exact_parts optional; if present MUST be a positive integer.
• parts optional; if present MUST be an object.
• If parts is present:

• keys MUST be exactly p0..pN (dense, zero-based, no gaps)
• each pK MUST be an object containing:

• optional name (string; documentation only)
• required apply which MUST be a Node Object (see §5.1)

Invalid:

• invalid_split_shape
• invalid_split_parts_indexing
• invalid_split_part_apply_shape

Semantics

• Split input string on literal sep.
• If exact_parts present and part count differs: fail

• runtime code split_exact_parts_mismatch
• If parts present: apply each pK.apply to the Kth part string.
• Any failing part fails split.

Note:

• apply is a Node Object, so you can use all, pred, labels, etc. directly.

5.7 labels

Shape

Rules:

• labels MUST be an object.
• sep MUST be a non-empty string.
• min_parts optional; if present MUST be a positive integer.
• each MUST be a Node Object.

Invalid:

• schema error invalid_labels_shape

Semantics

• Split on literal sep.
• If min_parts present and count < min_parts: fail

• runtime code labels_min_parts_violation
• Apply each to every part string.
• If any part fails, labels fails.

6. Charset registry (v1 ASCII-only)

This profile permits named charsets referenced by pred.charset.

Charset definition shape (v1)

Rules:

• charsets is a registry object defined by the AEOS Schema Profile (location not specified here).
• ascii_ranges optional; if present MUST be an object of ranges.

• each range MUST have from and to as single ASCII characters.
• literals optional; if present MUST be an object whose values are single ASCII characters.
• Any non-ASCII character in v1 charset definitions is invalid:

• schema error invalid_charset_definition

7. Error reporting and codes

7.1 Runtime pattern failures (data validation)

When a pattern fails on data, emit an error with:

• path = rule path being validated
• span = span of the data StringLiteral
• phase = "schema_validation"
• code = appropriate runtime code

Minimum runtime codes:

• pattern_mismatch // fallback
• length_violation
• predicate_violation
• whitespace_forbidden
• charset_violation
• split_exact_parts_mismatch
• labels_min_parts_violation
• constraint_inapplicable

7.2 Schema-shape failures (schema validation)

Invalid pattern/schema structures MUST be reported as schema errors (same envelope), using:

• invalid_pattern_shape
• unknown_pattern_node
• invalid_node_object_shape
• invalid_all_clause_shape
• invalid_any_clause_shape
• invalid_not_shape
• invalid_split_shape
• invalid_split_parts_indexing
• invalid_split_part_apply_shape
• invalid_labels_shape
• unknown_predicate_kind
• invalid_length_predicate
• invalid_contains_predicate
• invalid_starts_with_predicate
• invalid_ends_with_predicate
• invalid_no_whitespace_predicate
• unknown_charset
• invalid_charset_definition

Implementation-specific schema codes MUST use vendor prefix:

• vendor:code_name

8. Determinism and prohibitions

8.1 Ordering

Evaluation order MUST be lexical order in the AEON source for:

• entries under all
• entries under any
• split.parts via p0..pN

8.2 Full-match model

This pattern system is a full-string validation model. Substring intent must be explicit via predicates (contains, etc.). There is no implicit substring search operator.

8.3 Anti semantic creep

Validators MUST NOT use this pattern system to claim real-world semantic validity:

• no RFC-complete email validity
• no calendar correctness for date-like strings
• no DNS lookups
• no reference resolution for validation
• no coercion/normalization

9. Canonical example (email-shaped, form-only)