Skip to content

features.md

Latest commit

 

History

History
408 lines (297 loc) · 14.1 KB

features.md

File metadata and controls

408 lines (297 loc) · 14.1 KB
Raw

EntID capabilities v1

A capability ID designates an exact and frozen set of operations, fields, bounds and semantics. That set can never be widened or reinterpreted. IDs are never renumbered and never reused. A new operation, a new variant of an operation or any observable change always receives a new ID, even when it is conceptually close to an existing capability.

An engine publishes the list of capability IDs it implements and refuses to load a bundle declaring a single unknown ID.

Registry

ID Name Content
1 CORE_GRAPH_V1 programs, topological nodes, typed values
2 ASCII_AND_WHITESPACE_V1 ASCII classes and the frozen whitespace table
3 CANONICALIZATION_BASIC_V1 trim, uppercase, remove, prefix, pad, insert
4 CANONICALIZATION_CONDITIONAL_V1 when and predicates over the current value
5 IDENTIFIER_DISPATCH_V1 kind/country/prefixes, separated alias spaces and two phase selection
10 STRING_VIEWS_V1 slice, before/after, concat, absence
11 CAPTURES_AND_CALLS_V1 captures and program reuse
20 FORMAT_ASSERTIONS_V1 predicates and ordered assertions
21 PROFILES_V1 compatible and strict_current
30 CHECKSUM_TRISTATE_V1 valid, invalid, unsupported and branching
31 CHECKSUM_LUHN_V1 Luhn
32 CHECKSUM_MOD97_V1 ISO 7064 / modulo 97
33 CHECKSUM_WEIGHTED_V1 weighted sums, alignments and remainders
34 CHECKSUM_COMPARE_CONSTANT_V1 comparison against a literal constant
35 CHECKSUM_INTEGER_PREDICATE_V1 branching on the value of an integer
40 PROVENANCE_V1 sources linked to definitions
41 PROVENANCE_TIER_V1 how close a source sits to the authority
42 CHECKSUM_CUSTOM_ALPHABET_V1 weighted sums over an issuer's own alphabet

1 - CORE_GRAPH_V1

Programs, topological nodes, typed values.

Frozen content:

  • RuleBundle, Program, Node and the ValueType enum.
  • Programs are typed acyclic graphs whose nodes only reference strictly lower indices.
  • root_node designates the single result node of a program.
  • Structural limits of docs/ir.md section "Execution limits".
  • Rejection of an absent oneof operation, of an UNSPECIFIED enum value and of any unknown Protobuf field at any depth.

Operations requiring this capability:

  • ASSERTION_OP_KIND_REQUIRE
  • ASSERTION_OP_KIND_SEQUENCE
  • CALL_OP_KIND_CHECKSUM
  • CALL_OP_KIND_FORMAT
  • CANONICALIZATION_OP_KIND_APPEND
  • CANONICALIZATION_OP_KIND_INSERT
  • CANONICALIZATION_OP_KIND_LEFT_PAD
  • CANONICALIZATION_OP_KIND_PREPEND
  • CANONICALIZATION_OP_KIND_PREPEND_COUNTRY_IF_MISSING
  • CANONICALIZATION_OP_KIND_REMOVE_CHARS
  • CANONICALIZATION_OP_KIND_REMOVE_WHITESPACE
  • CANONICALIZATION_OP_KIND_REPLACE_PREFIX
  • CANONICALIZATION_OP_KIND_SEQUENCE
  • CANONICALIZATION_OP_KIND_TRIM_WHITESPACE
  • CANONICALIZATION_OP_KIND_UPPERCASE_ASCII
  • CANONICALIZATION_OP_KIND_WHEN
  • CHECKSUM_OP_KIND_ALL_CHECKS
  • CHECKSUM_OP_KIND_ANY_CHECK
  • CHECKSUM_OP_KIND_CHOOSE
  • CHECKSUM_OP_KIND_COMPARE_CONSTANT
  • CHECKSUM_OP_KIND_COMPARE_DIGIT
  • CHECKSUM_OP_KIND_COMPARE_SLICE
  • CHECKSUM_OP_KIND_ISO7064_MOD97_10
  • CHECKSUM_OP_KIND_LUHN
  • CHECKSUM_OP_KIND_UNSUPPORTED
  • CHECKSUM_OP_KIND_WHEN
  • INTEGER_OP_KIND_COMPLEMENT
  • INTEGER_OP_KIND_DIGITS_TO_INTEGER
  • INTEGER_OP_KIND_MODULO
  • INTEGER_OP_KIND_MOD_DIGITS
  • INTEGER_OP_KIND_REMAINDER_MAP
  • INTEGER_OP_KIND_WEIGHTED_SUM
  • PREDICATE_OP_KIND_ALL
  • PREDICATE_OP_KIND_ANY
  • PREDICATE_OP_KIND_ASCII_ALPHANUMERIC
  • PREDICATE_OP_KIND_ASCII_CHARSET
  • PREDICATE_OP_KIND_ASCII_DIGITS
  • PREDICATE_OP_KIND_ASCII_UPPER_LETTERS
  • PREDICATE_OP_KIND_CHAR_AT_IN
  • PREDICATE_OP_KIND_CONTAINS
  • PREDICATE_OP_KIND_ENDS_WITH
  • PREDICATE_OP_KIND_EQUALS
  • PREDICATE_OP_KIND_INTEGER_IS
  • PREDICATE_OP_KIND_IS_ABSENT
  • PREDICATE_OP_KIND_IS_EMPTY
  • PREDICATE_OP_KIND_LENGTH_BETWEEN
  • PREDICATE_OP_KIND_LENGTH_EQ
  • PREDICATE_OP_KIND_LENGTH_IN
  • PREDICATE_OP_KIND_NOT
  • PREDICATE_OP_KIND_PREFIX_IN
  • PREDICATE_OP_KIND_PROFILE_IS
  • PREDICATE_OP_KIND_STARTS_WITH
  • STRING_OP_KIND_AFTER_FIRST
  • STRING_OP_KIND_BEFORE_FIRST
  • STRING_OP_KIND_CONCAT
  • STRING_OP_KIND_CONSTANT
  • STRING_OP_KIND_COUNTRY_CODE
  • STRING_OP_KIND_SLICE
  • STRING_OP_KIND_SLICE_FROM
  • STRING_OP_KIND_SLICE_TO
  • STRING_OP_KIND_STRIP_PREFIX
  • STRING_OP_KIND_SUBJECT
  • STRING_OP_KIND_VALUE

2 - ASCII_AND_WHITESPACE_V1

ASCII classes and the frozen whitespace table.

Frozen content:

  • ASCII digit class U+0030..U+0039.
  • ASCII upper letter class U+0041..U+005A, ASCII lower letter class U+0061..U+007A.
  • The frozen whitespace_v1 table: U+0009..U+000D, U+0020, U+0085, U+00A0, U+1680, U+2000..U+200A, U+2028, U+2029, U+202F, U+205F, U+3000, U+FEFF.
  • uppercase_ascii maps only a..z to A..Z and never consults a locale.
  • Code point based positions and lengths.

Operations requiring this capability:

  • CANONICALIZATION_OP_KIND_REMOVE_WHITESPACE
  • CANONICALIZATION_OP_KIND_TRIM_WHITESPACE
  • CANONICALIZATION_OP_KIND_UPPERCASE_ASCII
  • PREDICATE_OP_KIND_ASCII_ALPHANUMERIC
  • PREDICATE_OP_KIND_ASCII_CHARSET
  • PREDICATE_OP_KIND_ASCII_DIGITS
  • PREDICATE_OP_KIND_ASCII_UPPER_LETTERS

3 - CANONICALIZATION_BASIC_V1

Trim, uppercase, remove, prefix, pad, insert.

Frozen content:

  • Sequential canonicalization programs and the SEQUENCE step.
  • Unconditional canonicalization steps listed in docs/ir.md.
  • A canonicalization program never truncates and never fails on user input.

Operations requiring this capability:

  • CANONICALIZATION_OP_KIND_APPEND
  • CANONICALIZATION_OP_KIND_INSERT
  • CANONICALIZATION_OP_KIND_LEFT_PAD
  • CANONICALIZATION_OP_KIND_PREPEND
  • CANONICALIZATION_OP_KIND_PREPEND_COUNTRY_IF_MISSING
  • CANONICALIZATION_OP_KIND_REMOVE_CHARS
  • CANONICALIZATION_OP_KIND_REMOVE_WHITESPACE
  • CANONICALIZATION_OP_KIND_REPLACE_PREFIX
  • CANONICALIZATION_OP_KIND_SEQUENCE
  • CANONICALIZATION_OP_KIND_TRIM_WHITESPACE
  • CANONICALIZATION_OP_KIND_UPPERCASE_ASCII

4 - CANONICALIZATION_CONDITIONAL_V1

when and predicates over the current value.

Frozen content:

  • The WHEN canonicalization step.
  • Evaluation of a predicate against the value current at the moment the step runs.
  • No memoization is observable across canonicalization steps.

Operations requiring this capability:

  • CANONICALIZATION_OP_KIND_WHEN

5 - IDENTIFIER_DISPATCH_V1

Kind/country/prefixes, separated alias spaces and two phase selection.

Frozen content:

  • IdentifierDispatcher, CountryAlias, DispatchTarget and the pre-canonicalization program.
  • The nine step dispatch algorithm of docs/ir.md.
  • Separated alias spaces for kinds, countries and prefixes.
  • GLOBAL targets expressed by the absence of country_code.
  • The country_code() string constructor and the PREPEND_COUNTRY_IF_MISSING canonicalization step.

Operations requiring this capability:

  • CANONICALIZATION_OP_KIND_PREPEND_COUNTRY_IF_MISSING
  • STRING_OP_KIND_COUNTRY_CODE

10 - STRING_VIEWS_V1

Slice, before/after, concat, absence.

Frozen content:

  • Possibly absent string views and their propagation rules.
  • The string view constructors listed in docs/ir.md.
  • IS_ABSENT, the only predicate that observes absence as true.

Operations requiring this capability:

  • PREDICATE_OP_KIND_IS_ABSENT
  • STRING_OP_KIND_AFTER_FIRST
  • STRING_OP_KIND_BEFORE_FIRST
  • STRING_OP_KIND_CONCAT
  • STRING_OP_KIND_SLICE
  • STRING_OP_KIND_SLICE_FROM
  • STRING_OP_KIND_SLICE_TO
  • STRING_OP_KIND_STRIP_PREFIX

11 - CAPTURES_AND_CALLS_V1

Captures and program reuse.

Frozen content:

  • Program.captures and the per format capture limit.
  • CallOperation for use_format and apply_checksum.
  • The acyclic, typed call graph of static depth at most 32.
  • Program.subject_node and the subject supplied by a caller.

Operations requiring this capability:

  • CALL_OP_KIND_CHECKSUM
  • CALL_OP_KIND_FORMAT

20 - FORMAT_ASSERTIONS_V1

Predicates and ordered assertions.

Frozen content:

  • AssertionOperation with SEQUENCE and REQUIRE.
  • Ordered evaluation: the first failing assertion determines the reason code and the message key.
  • The non ASCII specific predicates listed in docs/ir.md.
  • Reason codes usable by REQUIRE, restricted to codes that prove invalidity.

Operations requiring this capability:

  • ASSERTION_OP_KIND_REQUIRE
  • ASSERTION_OP_KIND_SEQUENCE
  • CALL_OP_KIND_FORMAT
  • PREDICATE_OP_KIND_ALL
  • PREDICATE_OP_KIND_ANY
  • PREDICATE_OP_KIND_CHAR_AT_IN
  • PREDICATE_OP_KIND_CONTAINS
  • PREDICATE_OP_KIND_ENDS_WITH
  • PREDICATE_OP_KIND_EQUALS
  • PREDICATE_OP_KIND_IS_EMPTY
  • PREDICATE_OP_KIND_LENGTH_BETWEEN
  • PREDICATE_OP_KIND_LENGTH_EQ
  • PREDICATE_OP_KIND_LENGTH_IN
  • PREDICATE_OP_KIND_NOT
  • PREDICATE_OP_KIND_PREFIX_IN
  • PREDICATE_OP_KIND_STARTS_WITH

21 - PROFILES_V1

Compatible and strict_current.

Frozen content:

  • IdentifierDefinition.default_profile restricted to compatible and strict_current.
  • The PROFILE_IS predicate.
  • compatible is the normative default and never restricts the canonicalization shared by both profiles.

Operations requiring this capability:

  • PREDICATE_OP_KIND_PROFILE_IS

30 - CHECKSUM_TRISTATE_V1

Valid, invalid, unsupported and branching.

Frozen content:

  • ChecksumOperation and the tri-state checksum outcome.
  • CHOOSE, WHEN, ALL_CHECKS, ANY_CHECK and UNSUPPORTED.
  • COMPARE_DIGIT and COMPARE_SLICE.
  • The integer constructors DIGITS_TO_INTEGER, MOD_DIGITS, MODULO, COMPLEMENT and REMAINDER_MAP with their checked arithmetic bounds.
  • Propagation of an indeterminate integer to unsupported/unsupported_checksum.
  • IdentifierDefinition.absent_checksum_reason.

Operations requiring this capability:

  • CALL_OP_KIND_CHECKSUM
  • CHECKSUM_OP_KIND_ALL_CHECKS
  • CHECKSUM_OP_KIND_ANY_CHECK
  • CHECKSUM_OP_KIND_CHOOSE
  • CHECKSUM_OP_KIND_COMPARE_CONSTANT
  • CHECKSUM_OP_KIND_COMPARE_DIGIT
  • CHECKSUM_OP_KIND_COMPARE_SLICE
  • CHECKSUM_OP_KIND_ISO7064_MOD97_10
  • CHECKSUM_OP_KIND_LUHN
  • CHECKSUM_OP_KIND_UNSUPPORTED
  • CHECKSUM_OP_KIND_WHEN
  • INTEGER_OP_KIND_COMPLEMENT
  • INTEGER_OP_KIND_DIGITS_TO_INTEGER
  • INTEGER_OP_KIND_MODULO
  • INTEGER_OP_KIND_MOD_DIGITS
  • INTEGER_OP_KIND_REMAINDER_MAP
  • INTEGER_OP_KIND_WEIGHTED_SUM
  • PREDICATE_OP_KIND_INTEGER_IS

31 - CHECKSUM_LUHN_V1

Luhn.

Frozen content:

  • The LUHN checksum operation over ASCII digits only.

Operations requiring this capability:

  • CHECKSUM_OP_KIND_LUHN

32 - CHECKSUM_MOD97_V1

ISO 7064 / modulo 97.

Frozen content:

  • The ISO7064_MOD97_10 checksum operation with base 36 expansion of ASCII letters.

Operations requiring this capability:

  • CHECKSUM_OP_KIND_ISO7064_MOD97_10

33 - CHECKSUM_WEIGHTED_V1

Weighted sums, alignments and remainders.

Frozen content:

  • The WEIGHTED_SUM integer operation.
  • The WeightAlignment values LEFT, RIGHT and CYCLE.
  • The CharMapping values DIGIT_VALUE and ALNUM_BASE36.

Operations requiring this capability:

  • INTEGER_OP_KIND_WEIGHTED_SUM

34 - CHECKSUM_COMPARE_CONSTANT_V1

Comparison against a literal constant.

Frozen content:

  • The COMPARE_CONSTANT checksum operation.
  • It closes the gap left by COMPARE_DIGIT and COMPARE_SLICE, which can only compare a computed integer against part of the value being checked. A rule stating that a remainder must equal zero has nothing in the value to compare against.

Operations requiring this capability:

  • CHECKSUM_OP_KIND_COMPARE_CONSTANT

35 - CHECKSUM_INTEGER_PREDICATE_V1

Branching on the value of an integer.

Frozen content:

  • The INTEGER_IS predicate.
  • Every other predicate reads a string, so a checksum could compare a remainder but never branch on it. Registers that recompute their sum with a second set of weights when the first remainder reaches a given value need exactly that.

Operations requiring this capability:

  • PREDICATE_OP_KIND_INTEGER_IS

40 - PROVENANCE_V1

Sources linked to definitions.

Frozen content:

  • Source and IdentifierDefinition.sources, sorted by source id.
  • Every rule able to reject an input carries at least one source.

This capability declares no operation of its own: it is required by the bundle level constructs listed above.

41 - PROVENANCE_TIER_V1

How close a source sits to the authority.

Frozen content:

  • Source.tier and the SourceTier enumeration.
  • It is a capability of its own rather than an addition to PROVENANCE_V1, whose content is frozen: a field added to a frozen capability reaches an engine as an unknown field, which reads as a forged bundle rather than as the version gap it is.
  • Only a stated tier requires it. tier is not optional in the schema, so a Source that omits the field and one that sets SOURCE_TIER_UNSPECIFIED are the same bytes; UNSPECIFIED therefore means the source states no tier, and a bundle whose sources all state none does not declare this capability. Refusing UNSPECIFIED would make this capability mandatory the moment PROVENANCE_V1 is, which is the opposite of the independence a separate id exists to give. A value outside the enumeration remains invalid_ruleset.

This capability declares no operation of its own: it is required by the bundle level constructs listed above.

42 - CHECKSUM_CUSTOM_ALPHABET_V1

Weighted sums over an issuer's own alphabet.

Frozen content:

  • The CharMapping value CUSTOM_ALPHABET, and the alphabet field of IntegerOperation that carries its ordered code points.
  • The value of a code point is its index in that alphabet. A code point absent from it makes the sum indeterminate, exactly as a letter does under DIGIT_VALUE.
  • It exists because an issuer's alphabet is often neither base 10 nor base 36. Letters that are misread as digits get dropped, and every letter after the gap shifts: the Chinese unified social credit code omits I, O, S, V and Z, so its J is 18 where ALNUM_BASE36 makes it 19. Without this, such a checksum cannot be stated at all, and a published algorithm that cannot be stated has to be reported unsupported.

This capability declares no operation of its own: it is required by the bundle level constructs listed above.