expressir 2.4.35 → 2.4.37

data/docs/_guides/interop/json-schema.adoc

@@ -0,0 +1,88 @@
+---
+title: JSON Schema Export
+parent: Interop Exports
+grand_parent: Guides
+nav_order: 1
+---
+
+= JSON Schema Export
+
+== Purpose
+
+`Expressir::Interop::JsonSchema` renders one EXPRESS schema as a JSON
+Schema 2020-12 document. The mapping is a project contribution; this
+guide records every decision so consumers can depend on it.
+
+== Mapping decisions
+
+Entities::
+Each entity becomes a definition under `$defs`. An entity with
+supertypes is an `allOf` of one `$ref` per `SUBTYPE OF` parent plus an
+object schema holding its own explicit attributes. The subtype closure
+is therefore expressed compositionally rather than duplicated.
+Attributes appear in declaration order (inherited attributes come
+through the parent branch of `allOf`). An entity without supertypes is
+the object schema itself with a `title`.
+
+Explicit attributes::
+Only explicit attributes are exported. Derived and inverse attributes
+are not part of the Part 21 exchange structure and are omitted.
+
+OPTIONAL attributes::
+An optional attribute is left out of `required` and its type becomes
+`anyOf: [type, {type: null}]` — absent and explicit `$` both validate.
+
+Types::
+`INTEGER` → `integer`; `REAL`/`NUMBER` → `number`; `STRING` → `string`;
+`BOOLEAN` → `boolean`; `LOGICAL` → `enum: [true, false, null]`
+(`UNKNOWN` maps to null); `BINARY` → a string matching `[01]*`.
+
+Enumerations::
+An `ENUMERATION` becomes `{type: string, enum: [...]}`. `BASED_ON`
+chains are folded into the full domain, matching Annex G semantics.
+
+SELECT::
+A named select becomes `{anyOf: [$ref, ...]}` over its items;
+`BASED_ON` chains are folded into the full item list. Items referencing
+declarations are `$ref`s.
+
+Aggregates::
+`LIST`, `ARRAY`, `SET` and `BAG` become JSON arrays. `minItems` and
+`maxItems` come from the declared bounds (an unbounded upper bound is
+omitted). `SET`, and `LIST ... OF UNIQUE`, set `uniqueItems: true`.
+
+Names::
+EXPRESS identifiers are used verbatim. EXPRESS is case-insensitive but
+preserves case; JSON property names are case-sensitive, so consumers
+must use the declared spelling.
+
+Root document::
+The root carries `$schema`, `$id`, `title`, every declaration in
+`$defs`, and an `anyOf` over the entity definitions (one JSON document
+describes one entity instance). A schema with no entities has no root
+`anyOf`. Because an instance of a subtype also satisfies each ancestor
+definition, a consumer that knows the EXPRESS entity of an instance
+should validate against that entity's definition under `$defs` rather
+than the root `anyOf`.
+
+Not exported::
+`WHERE` and `UNIQUE` rules, `GENERIC`/`GENERIC_ENTITY`, constants and
+subtype constraint expressions. They have no direct JSON Schema
+counterpart and are left to the consumer's semantic layer.
+
+== Programmatic use
+
+[source,ruby]
+----
+schema = Expressir::Express::Parser.from_file("example.exp").schemas.first
+document = Expressir::Interop::JsonSchema.new(schema).to_json
+File.write("example.schema.json", document)
+----
+
+== Part 21 population check
+
+Part 21 instances serialize to JSON objects keyed by attribute name in
+the Part 21 slot order (supertype attributes first), with `$` and `*`
+omitted or null, enum values as strings, and references expanded
+in-line (a cycle guard falls back to `{"$ref": "#id"}`). The acceptance
+spec validates the Annex H population against the exported schema.

data/docs/_guides/interop/owl-rdf.adoc

@@ -0,0 +1,87 @@
+---
+title: OWL/RDF Export
+parent: Interop Exports
+grand_parent: Guides
+nav_order: 2
+---
+
+= OWL/RDF Export
+
+== Purpose
+
+`Expressir::Interop::Owl` renders one EXPRESS schema as OWL 2 in Turtle.
+The approach generalizes the ifcOWL lineage from IFC to arbitrary
+EXPRESS. This guide records the decisions and the literature the
+approach follows.
+
+== Lineage
+
+The mapping follows the published EXPRESS-to-OWL work:
+
+* J. Beetz, J. van Leeuwen, B. de Vries, "IfcOWL: A case of transforming
+  EXPRESS schemas into ontologies", _Artificial Intelligence for
+  Engineering Design, Analysis and Manufacturing_ 23(1), 2009, 89-101.
+* P. Pauwels, W. Terkaj, "EXPRESS to OWL for construction industry:
+  Towards a recommendable and usable ifcOWL ontology", _Automation in
+  Construction_ 63, 2016, 100-133.
+* W. Terkaj, A. Sojic, "Ontology-based representation of IFC EXPRESS
+  rules: An enhancement of the ifcOWL ontology", _Automation in
+  Construction_ 57, 2015, 188-201.
+
+The last reference is the source of our scope decision on WHERE rules:
+this exporter does not translate rule bodies (see below).
+
+== Mapping decisions
+
+Entities::
+Each entity becomes an `owl:Class` with one `rdfs:subClassOf` per
+`SUBTYPE OF` parent. Abstract entities carry an `rdfs:comment
+"EXPRESS ABSTRACT SUPERTYPE"`; they are not made equivalent to their
+subtype union.
+
+Explicit attributes::
+Each explicit attribute becomes a property with `rdfs:domain` on its
+entity and `rdfs:range` from the attribute type. Entity, select and
+enumeration ranges are object properties; primitive ranges are
+datatype properties. `OPTIONAL` is recorded as an `rdfs:comment`
+rather than an OWL cardinality restriction, because cardinalities
+belong to the entity class and would multiply restrictions per
+attribute.
+
+Primitive types::
+`INTEGER` → `xsd:integer`; `REAL`/`NUMBER` → `xsd:double`; `STRING` →
+`xsd:string`; `BOOLEAN` → `xsd:boolean`; `BINARY` → `xsd:hexBinary`.
+`LOGICAL` maps to `xsd:boolean`; EXPRESS `UNKNOWN` has no XSD
+counterpart and is a documented loss. Defined types over primitives are
+emitted as `rdfs:Datatype` with `owl:equivalentClass` to the XSD type.
+
+Aggregates::
+`LIST`, `ARRAY`, `SET` and `BAG` attributes are object properties with
+range `rdf:List`; element type and ordering live in the RDF collection.
+
+SELECT::
+A named select becomes an `owl:Class` with an `owl:equivalentClass`
+restriction whose `owl:unionOf` lists the item classes (union
+semantics). `BASED_ON` chains are folded into the item list.
+
+Enumerations::
+An enumeration becomes an `owl:Class`; each item becomes an
+`owl:NamedIndividual` of that class. `BASED_ON` chains are folded.
+
+Not exported::
+`WHERE` and `UNIQUE` rule bodies, subtype constraint expressions,
+derived and inverse attributes, and aggregate bounds. Rule translation
+is a research problem in its own right (see Terkaj & Sojic); consumers
+that need rule semantics should consume the EXPRESS model directly.
+
+== Programmatic use
+
+[source,ruby]
+----
+schema = Expressir::Express::Parser.from_file("example.exp").schemas.first
+turtle = Expressir::Interop::Owl.new(
+  schema,
+  base_iri: "https://example.org/my-schema#",
+).export
+File.write("example.ttl", turtle)
+----

data/docs/_guides/reference/checker-notes.adoc

@@ -0,0 +1,55 @@
+= Checker note-id catalog
+
+// Generated from lib/expressir/express/checker.rb by
+// `rake reference:notes`. Do not edit by hand; the reference
+// spec fails when this file is stale.
+
+== Purpose
+
+Every note id the Checker can raise, with the number of call
+sites in the implementation. New checks use `:check_*` ids;
+the conformance-derived ids (`:check_expr_*`, `:check_dialect_*`)
+cite their clause in the note message.
+
+[cols="3,1", options="header"]
+|===
+| Note id | Call sites
+
+| `check_agg_type` | 1
+| `check_attrib_name_fun` | 1
+| `check_attribute_redeclaration` | 3
+| `check_dialect_2004_only` | 1
+| `check_dialect_deprecated` | 1
+| `check_dialect_mixed` | 1
+| `check_duplicate_declaration` | 1
+| `check_enumeration_extended_type` | 1
+| `check_expr_assignment_type` | 1
+| `check_expr_initializer_type` | 1
+| `check_expr_operand_domain` | 7
+| `check_expr_return` | 2
+| `check_expr_unique_duplicate` | 1
+| `check_expr_where_boolean` | 1
+| `check_interface_kind_restriction` | 1
+| `check_inverse_attrib_ref` | 2
+| `check_inverse_derive` | 1
+| `check_inverse_entity` | 1
+| `check_inverse_inverse` | 1
+| `check_schema_iface_resource_duplicate` | 1
+| `check_schema_interface_redundant` | 1
+| `check_select_extended_type` | 1
+| `check_select_named_type` | 1
+| `check_self_schema_reference` | 2
+| `check_string_no_entity` | 1
+| `check_subtype_cycle` | 1
+| `check_subtype_ref` | 1
+| `check_subtypeof_invalid` | 1
+| `check_supertype_ref` | 2
+| `check_unique_name_pattern` | 1
+| `check_unresolved_ref` | 3
+| `check_where_name_pattern` | 1
+| `qualified_attrib_attr_not_found` | 1
+| `qualified_attrib_group_not_ancestor` | 1
+| `qualified_attrib_group_not_found` | 1
+|===
+
+The catalog covers 35 note ids.

data/docs/_guides/reference/checker.adoc

@@ -0,0 +1,36 @@
+---
+title: Checker
+parent: Reference
+grand_parent: Guides
+nav_order: 3
+---
+
+= Checker
+
+== Purpose
+
+`Expressir::Express::Checker` performs static, edition-aware semantic
+checks over a parsed repository. Notes carry a stable id, a severity,
+the schema, a message citing the ISO 10303-11 clause where the check
+comes from, and the offending model node.
+
+== Note ids
+
+The catalog is generated from the checker source and published as the
+"Checker note-id catalog" guide. New conformance-derived
+checks use `:check_expr_*`, `:check_statement_*`, `:check_rule_*` and
+`:check_dialect_*` ids; the message carries the clause.
+
+== Dialects
+
+`Checker.new(repository, dialect: :"10303-11:1994")` reports
+2004-only constructs as errors when targeting the 1994 edition;
+`dialect: :"10303-11:2004"` reports the Annex K deprecated inline
+subtype-constraint syntax as warnings. Without a dialect the report is
+unchanged. See the Dialect awareness task notes (TODO.sota/06).
+
+== Severities and validity
+
+`Checker#valid?` is true when no error-severity note was raised.
+Indeterminate expression results are not violations; only a proven
+false WHERE rule is.

data/docs/_guides/reference/evaluator.adoc

@@ -0,0 +1,40 @@
+---
+title: Evaluator
+parent: Reference
+grand_parent: Guides
+nav_order: 6
+---
+
+= Evaluator
+
+== Purpose
+
+`Expressir::Eval` executes EXPRESS: expressions over a value model,
+functions (parameters, locals, control flow), and WHERE rules over a
+Part 21 population.
+
+== Expressions
+
+`Expressir::Eval::Expression` implements ISO 10303-11 clause 12:
+arithmetic with result typing, logical tables (12.4), relational
+orderings (12.2.1), IN (12.2.3), LIKE patterns (12.2.5, table 11),
+intervals, aggregate operations (tables 16-18 including element
+singletons), QUERY, and indeterminate propagation. The value model
+lives in `Values`: logical constants, enumeration and binary values,
+aggregates and Part 21 instances.
+
+== Execution
+
+`Expressir::Eval::Interpreter` runs functions and procedures:
+assignment (including indexed), IF/CASE, WHILE/UNTIL/increment REPEAT
+with SKIP and ESCAPE, RETURN (falling off the end is an error), and the
+builtin set A (`ABS` … `VALUE`, `TYPEOF`, `USEDIN`). Populations are
+read through `Expressir::Eval::Environment`, which maps Part 21 slots
+in clause 12 order.
+
+== Rules
+
+`Expressir::Eval::Rules.check(population, schema)` evaluates each
+instance's entity WHERE rules with `SELF` and both bare and
+`SELF\attribute` bindings. A rule is violated only when it evaluates
+to false; indeterminate is not a violation (clause 9.4).

data/docs/_guides/reference/grammar-crosswalk.adoc

@@ -0,0 +1,299 @@
+= Grammar cross-walk
+
+// Generated by `rake reference:crosswalk` from
+// lib/expressir/express/grammar/parser.rb and the Annex A snapshot.
+// Do not edit by hand; the reference spec fails when this file is stale.
+
+== Purpose
+
+Every parsanol grammar rule is mapped to the ISO 10303-11:2004
+Annex A production it implements. Divergences from the standard
+grammar are classified with one of these statuses:
+
+* `aligned` — The grammar rule implements the same-named Annex production.
+* `decomposed` — The grammar rule is one piece of an Annex production that the PEG splits.
+* `token` — Literal operator/delimiter token; Annex A names keywords but not punctuation.
+* `lexical` — Character-class or whitespace handling inlined in the PEG (clause 7).
+* `internal` — PEG-internal rule with no Annex counterpart.
+* `support-code` — Handled by supporting Ruby code rather than a grammar rule.
+
+== Rules
+
+[cols="2,3,1,4", options="header"]
+|===
+| Parsanol rule | Annex A production | Status | Note
+
+| `abstractEntityDeclaration` | abstract_entity_declaration | aligned | 
+| `abstractSupertype` | abstract_supertype | aligned | 
+| `abstractSupertypeDeclaration` | abstract_supertype_declaration | aligned | 
+| `actualParameterList` | actual_parameter_list | aligned | 
+| `addLikeOp` | add_like_op | aligned | 
+| `aggregateInitializer` | aggregate_initializer | aligned | 
+| `aggregateSource` | aggregate_source | aligned | 
+| `aggregateType` | aggregate_type | aligned | 
+| `aggregationTypes` | aggregation_types | aligned | 
+| `algorithmHead` | algorithm_head | aligned | 
+| `aliasStmt` | alias_stmt | aligned | 
+| `anyKeyword` |  | internal | keyword guard that keeps identifiers from consuming reserved words
+| `arrayType` | array_type | aligned | 
+| `assignmentStmt` | assignment_stmt | aligned | 
+| `attributeDecl` | attribute_decl | aligned | 
+| `attributeId` | attribute_id | aligned | 
+| `attributeQualifier` | attribute_qualifier | aligned | 
+| `attributeRef` | attribute_ref | aligned | 
+| `bagType` | bag_type | aligned | 
+| `binaryLiteral` | binary_literal | aligned | 
+| `binaryType` | binary_type | aligned | 
+| `bit` | bit | aligned | 
+| `booleanType` | boolean_type | aligned | 
+| `bound1` | bound_1 | aligned | 
+| `bound2` | bound_2 | aligned | 
+| `boundSpec` | bound_spec | aligned | 
+| `builtInConstant` | built_in_constant | aligned | 
+| `builtInFunction` | built_in_function | aligned | 
+| `builtInProcedure` | built_in_procedure | aligned | 
+| `caseAction` | case_action | aligned | 
+| `caseLabel` | case_label | aligned | 
+| `caseStmt` | case_stmt | aligned | 
+| `compoundStmt` | compound_stmt | aligned | 
+| `concreteTypes` | concrete_types | aligned | 
+| `constantBody` | constant_body | aligned | 
+| `constantDecl` | constant_decl | aligned | 
+| `constantFactor` | constant_factor | aligned | 
+| `constantId` | constant_id | aligned | 
+| `constantRef` | constant_ref | aligned | 
+| `constructedTypes` | constructed_types | aligned | 
+| `declaration` | declaration | aligned | 
+| `delim` |  | lexical | the delimiter semicolon (7.3)
+| `deriveClause` | derive_clause | aligned | 
+| `derivedAttr` | derived_attr | aligned | 
+| `digit` | digit | aligned | 
+| `digits` | digits | aligned | 
+| `domainRule` | domain_rule | aligned | 
+| `element` | element | aligned | 
+| `embeddedRemark` | embedded_remark | aligned | 
+| `encodedCharacter` | encoded_character | aligned | 
+| `encodedStringLiteral` | encoded_string_literal | aligned | 
+| `entityBody` | entity_body | aligned | 
+| `entityConstructor` | entity_constructor | aligned | 
+| `entityDecl` | entity_decl | aligned | 
+| `entityHead` | entity_head | aligned | 
+| `entityId` | entity_id | aligned | 
+| `entityRef` | entity_ref | aligned | 
+| `enumerationExtension` | enumeration_extension | aligned | 
+| `enumerationId` | enumeration_id | aligned | 
+| `enumerationItem` | enumeration_items | decomposed | 
+| `enumerationItems` | enumeration_items | aligned | 
+| `enumerationRef` | enumeration_ref | aligned | 
+| `enumerationReference` | enumeration_reference | aligned | 
+| `enumerationType` | enumeration_type | aligned | 
+| `escapeStmt` | escape_stmt | aligned | 
+| `explicitAttr` | explicit_attr | aligned | 
+| `expression` | expression | aligned | 
+| `factor` | factor | aligned | 
+| `formalParameter` | formal_parameter | aligned | 
+| `functionCall` | function_call | aligned | 
+| `functionDecl` | function_decl | aligned | 
+| `functionHead` | function_head | aligned | 
+| `functionId` | function_id | aligned | 
+| `functionRef` | function_ref | aligned | 
+| `generalAggregationTypes` | general_aggregation_types | aligned | 
+| `generalArrayType` | general_array_type | aligned | 
+| `generalBagType` | general_bag_type | aligned | 
+| `generalListType` | general_list_type | aligned | 
+| `generalRef` | general_ref | aligned | 
+| `generalSetType` | general_set_type | aligned | 
+| `generalizedTypes` | generalized_types | aligned | 
+| `genericEntityType` | generic_entity_type | aligned | 
+| `genericType` | generic_type | aligned | 
+| `groupQualifier` | group_qualifier | aligned | 
+| `hexDigit` | hex_digit | aligned | 
+| `ifStmt` | if_stmt | aligned | 
+| `ifStmtElseStatements` | if_stmt | decomposed | 
+| `ifStmtStatements` | if_stmt | decomposed | 
+| `increment` | increment | aligned | 
+| `incrementControl` | increment_control | aligned | 
+| `index` | index | aligned | 
+| `index1` | index_1 | aligned | 
+| `index2` | index_2 | aligned | 
+| `indexQualifier` | index_qualifier | aligned | 
+| `instantiableType` | instantiable_type | aligned | 
+| `integerLiteral` | integer_literal | aligned | 
+| `integerType` | integer_type | aligned | 
+| `interfaceSpecification` | interface_specification | aligned | 
+| `interval` | interval | aligned | 
+| `intervalHigh` | interval_high | aligned | 
+| `intervalItem` | interval_item | aligned | 
+| `intervalLow` | interval_low | aligned | 
+| `intervalOp` | interval_op | aligned | 
+| `inverseAttr` | inverse_attr | aligned | 
+| `inverseAttrType` | inverse_attr | decomposed | 
+| `inverseClause` | inverse_clause | aligned | 
+| `letter` | letter | aligned | 
+| `listType` | list_type | aligned | 
+| `literal` | literal | aligned | 
+| `localDecl` | local_decl | aligned | 
+| `localVariable` | local_variable | aligned | 
+| `logicalExpression` | logical_expression | aligned | 
+| `logicalLiteral` | logical_literal | aligned | 
+| `logicalType` | logical_type | aligned | 
+| `multiplicationLikeOp` | multiplication_like_op | aligned | 
+| `namedTypeOrRename` | named_type_or_rename | aligned | 
+| `namedTypes` | named_types | aligned | 
+| `nullStmt` | null_stmt | aligned | 
+| `numberType` | number_type | aligned | 
+| `numericExpression` | numeric_expression | aligned | 
+| `octet` | octet | aligned | 
+| `oneOf` | one_of | aligned | 
+| `op_asterisk` |  | token | literal `*`
+| `op_colon` |  | token | literal `:`
+| `op_colon_equals_colon` |  | token | literal `:=:`
+| `op_colon_less_greater_colon` |  | token | literal `:<>:`
+| `op_comma` |  | token | literal `,`
+| `op_decl` |  | token | literal `:=`
+| `op_delim` |  | token | literal `;`
+| `op_double_asterisk` |  | token | literal `**`
+| `op_double_backslash` |  | token | literal `\`
+| `op_double_pipe` |  | token | literal `\|\|`
+| `op_equals` |  | token | literal `=`
+| `op_greater_equal` |  | token | literal `>=`
+| `op_greater_than` |  | token | literal `>`
+| `op_left_curly_brace` |  | token | literal `{`
+| `op_leftbracket` |  | token | literal `[`
+| `op_leftparen` |  | token | literal `(`
+| `op_less_equal` |  | token | literal `<=`
+| `op_less_greater` |  | token | literal `<>`
+| `op_less_than` |  | token | literal `<`
+| `op_minus` |  | token | literal `-`
+| `op_period` |  | token | literal `.`
+| `op_pipe` |  | token | literal `\|`
+| `op_plus` |  | token | literal `+`
+| `op_query_begin` |  | token | literal `<*`
+| `op_query_end` |  | token | literal `*>`
+| `op_question_mark` |  | token | literal `?`
+| `op_right_curly_brace` |  | token | literal `}`
+| `op_rightbracket` |  | token | literal `]`
+| `op_rightparen` |  | token | literal `)`
+| `op_slash` |  | token | literal `/`
+| `parameter` | parameter | aligned | 
+| `parameterId` | parameter_id | aligned | 
+| `parameterRef` | parameter_ref | aligned | 
+| `parameterType` | parameter_type | aligned | 
+| `population` | population | aligned | 
+| `precisionSpec` | precision_spec | aligned | 
+| `primary` | primary | aligned | 
+| `procedureCallStmt` | procedure_call_stmt | aligned | 
+| `procedureDecl` | procedure_decl | aligned | 
+| `procedureHead` | procedure_head | aligned | 
+| `procedureHeadParameter` | procedure_head | decomposed | 
+| `procedureId` | procedure_id | aligned | 
+| `procedureRef` | procedure_ref | aligned | 
+| `qualifiableFactor` | qualifiable_factor | aligned | 
+| `qualifiedAttribute` | qualified_attribute | aligned | 
+| `qualifier` | qualifier | aligned | 
+| `queryExpression` | query_expression | aligned | 
+| `realLiteral` | real_literal | aligned | 
+| `realType` | real_type | aligned | 
+| `redeclaredAttribute` | redeclared_attribute | aligned | 
+| `referenceClause` | reference_clause | aligned | 
+| `referencedAttribute` | referenced_attribute | aligned | 
+| `relOp` | rel_op | aligned | 
+| `relOpExtended` | rel_op_extended | aligned | 
+| `renameId` | rename_id | aligned | 
+| `repeatControl` | repeat_control | aligned | 
+| `repeatStmt` | repeat_stmt | aligned | 
+| `repetition` | repetition | aligned | 
+| `resourceOrRename` | resource_or_rename | aligned | 
+| `resourceRef` | resource_ref | aligned | 
+| `returnStmt` | return_stmt | aligned | 
+| `ruleDecl` | rule_decl | aligned | 
+| `ruleHead` | rule_head | aligned | 
+| `ruleId` | rule_id | aligned | 
+| `ruleLabelId` | rule_label_id | aligned | 
+| `ruleLabelRef` | rule_label_ref | aligned | 
+| `ruleRef` | rule_ref | aligned | 
+| `schemaBody` | schema_body | aligned | 
+| `schemaBodyDeclaration` | schema_body | decomposed | 
+| `schemaDecl` | schema_decl | aligned | 
+| `schemaId` | schema_id | aligned | 
+| `schemaRef` | schema_ref | aligned | 
+| `schemaVersionId` | schema_version_id | aligned | 
+| `selectExtension` | select_extension | aligned | 
+| `selectList` | select_list | aligned | 
+| `selectType` | select_type | aligned | 
+| `selector` | selector | aligned | 
+| `setType` | set_type | aligned | 
+| `sign` | sign | aligned | 
+| `simpleExpression` | simple_expression | aligned | 
+| `simpleFactor` | simple_factor | aligned | 
+| `simpleFactorExpression` | simple_factor | decomposed | 
+| `simpleFactorUnaryExpression` | simple_factor | decomposed | 
+| `simpleId` | simple_id | aligned | 
+| `simpleStringLiteral` | simple_string_literal | aligned | 
+| `simpleTypes` | simple_types | aligned | 
+| `skipStmt` | skip_stmt | aligned | 
+| `space` |  | lexical | whitespace between tokens (7.1)
+| `spaces` |  | lexical | whitespace between tokens (7.1)
+| `stmt` | stmt | aligned | 
+| `stringLiteral` | string_literal | aligned | 
+| `stringType` | string_type | aligned | 
+| `subsuper` | subsuper | aligned | 
+| `subtypeConstraint` | subtype_constraint | aligned | 
+| `subtypeConstraintBody` | subtype_constraint_body | aligned | 
+| `subtypeConstraintDecl` | subtype_constraint_decl | aligned | 
+| `subtypeConstraintHead` | subtype_constraint_head | aligned | 
+| `subtypeConstraintId` | subtype_constraint_id | aligned | 
+| `subtypeConstraintRef` | subtype_constraint_ref | aligned | 
+| `subtypeDeclaration` | subtype_declaration | aligned | 
+| `supertypeConstraint` | supertype_constraint | aligned | 
+| `supertypeExpression` | supertype_expression | aligned | 
+| `supertypeFactor` | supertype_factor | aligned | 
+| `supertypeRule` | supertype_rule | aligned | 
+| `supertypeTerm` | supertype_term | aligned | 
+| `syntax` | syntax | aligned | 
+| `tailRemark` | tail_remark | aligned | 
+| `term` | term | aligned | 
+| `totalOver` | total_over | aligned | 
+| `trivia` |  | lexical | whitespace and embedded remarks (7.1)
+| `typeDecl` | type_decl | aligned | 
+| `typeId` | type_id | aligned | 
+| `typeLabel` | type_label | aligned | 
+| `typeLabelId` | type_label_id | aligned | 
+| `typeLabelRef` | type_label_ref | aligned | 
+| `typeRef` | type_ref | aligned | 
+| `unaryOp` | unary_op | aligned | 
+| `underlyingType` | underlying_type | aligned | 
+| `uniqueClause` | unique_clause | aligned | 
+| `uniqueRule` | unique_rule | aligned | 
+| `untilControl` | until_control | aligned | 
+| `useClause` | use_clause | aligned | 
+| `variableId` | variable_id | aligned | 
+| `variableRef` | variable_ref | aligned | 
+| `whereClause` | where_clause | aligned | 
+| `whileControl` | while_control | aligned | 
+| `width` | width | aligned | 
+| `widthSpec` | width_spec | aligned | 
+|===
+
+== Annex A productions without a dedicated rule
+
+These productions are handled by supporting code rather than a
+grammar rule:
+
+[cols="3,1,5", options="header"]
+|===
+| Annex A production | Status | Handled by
+
+| `lparen_then_not_lparen_star` | lexical | embedded-remark lookahead in the PEG
+| `not_lparen_star` | lexical | embedded-remark lookahead in the PEG
+| `not_paren_star` | lexical | embedded-remark lookahead in the PEG
+| `not_paren_star_quote_special` | lexical | embedded-remark lookahead in the PEG
+| `not_paren_star_special` | lexical | embedded-remark lookahead in the PEG
+| `not_quote` | lexical | string-literal lookahead in the PEG
+| `not_rparen_star` | lexical | embedded-remark lookahead in the PEG
+| `not_rparen_star_then_rparen` | lexical | embedded-remark lookahead in the PEG
+| `remark` | support-code | remark scanning is performed by RemarkScanner/RemarkAttacher
+| `remark_ref` | support-code | remark scanning is performed by RemarkScanner/RemarkAttacher
+| `remark_tag` | support-code | remark scanning is performed by RemarkScanner/RemarkAttacher
+| `special` | lexical | character-class regex in the PEG (7.1)
+|===

data/docs/_guides/reference/index.adoc

@@ -0,0 +1,22 @@
+---
+title: Reference
+nav_order: 13
+has_children: true
+---
+
+= Reference
+
+== Purpose
+
+Citable, generated reference material. The grammar cross-walk and the
+checker note-id catalog are generated from the implementation and kept
+in sync by specs; the subsystem guides describe the architecture and
+the standard clauses each subsystem enforces.
+
+== Generating
+
+[source,shell]
+----
+bundle exec rake reference:crosswalk
+bundle exec rake reference:notes
+----

data/docs/_guides/reference/lsp.adoc

@@ -0,0 +1,41 @@
+---
+title: Language Server
+parent: Reference
+grand_parent: Guides
+nav_order: 7
+---
+
+= Language Server
+
+== Purpose
+
+`expressir-lsp` is a stdio language server (JSON-RPC 2.0, LSP 3.17)
+exposing the parser, checker and resolution machinery to editors.
+
+== Launch
+
+[source,shell]
+----
+bundle exec expressir-lsp
+----
+
+== Capabilities
+
+* full-sync documents (`didOpen`, `didChange`, `didSave`, `didClose`);
+* diagnostics from Checker notes, mapped through `NodePositionIndex`
+  and `LineMap` to UTF-16 ranges, plus parse-error diagnostics;
+* document symbols for schemas, entities, types, functions, procedures,
+  rules and attributes;
+* go-to-definition through the USE/REFERENCE ladder and its alias map;
+* references across all open documents;
+* hover with a PrettyFormatter excerpt;
+* rename across schemas, with edits applied in memory, every affected
+  document reparsed, SchemaCompare rejecting unrelated removals, and
+  the renamed schema re-emitted through the Formatter.
+
+== Incremental behaviour
+
+Changes reparse the document through the native/core parser path;
+identical text is a no-op and checker results are memoized per document
+set. Content-incremental parsing awaits an incremental API in the
+expressir-rs core.