expressir 2.4.31-aarch64-linux → 2.4.36-aarch64-linux

data/TODO.sota/03-conformance.md

@@ -0,0 +1,53 @@
+# 03 — Conformance: measure against the standard's own yardstick
+
+## Parts (each ships)
+
+1. Part 21 conformance corpus: extract the conformance-requirement
+   examples from the detached ISO 10303-21 source (annexes + body
+   worked examples) into fixtures; a gate spec runs the P21
+   reader/validator over every positive fixture (clean) and every
+   negative fixture (the intended note id, only).
+2. Grammar-conformance harness: property-based generation from the
+   ISO 10303-11 Annex A/B productions (finite fragments first:
+   declarations, then expressions). Invariants: parse→format→parse
+   idempotence, formatter output re-parses, ill-formed input rejected
+   with a diagnostic (no silent recovery on the strict faces).
+   Promoted to a nightly CI tier.
+3. G.1.7 closure: the BASED_ON enumeration-chain corpus fixture —
+   the last unaudited Annex G rule (annex-g-rules.md table tail).
+
+## Acceptance
+
+- `rake conformance` (or the spec tier) green; negatives fail with
+  exactly the intended note, positives with zero notes.
+
+## Status: done
+
+- Part 1 (Part 21 conformance corpus): the ISO 10303-21 detachment
+  examples are extracted to `spec/fixtures/p21/conformance/`:
+  annex-e-0/1 (named data sections), annex-h-0 (the worked exchange
+  structure, 13 instances), annex-i-0/1 (ANCHOR/REFERENCE), annex-j-0
+  (constants). `spec/expressir/p21/parser_conformance_spec.rb` parses
+  every positive fixture with zero notes and asserts the intended
+  failure for the forms this ladder does not implement yet (annex E
+  named sections and `..`, annex I ANCHOR/REFERENCE, annex J
+  constants/`....` and STEP-21-ED2 extended literals) — they fail
+  loudly, not silently. Malformed negatives are rejected.
+- Part 2 (grammar-conformance harness):
+  `spec/expressir/express/formatter_roundtrip_conformance_spec.rb`
+  asserts parse → format → parse structural idempotence over a fixture
+  slice, over generated fragments (Annex A/B production levels:
+  expression → simple_expression → term, declarations, arrays, QUERY,
+  unary/logical/relational forms, deterministically seeded), and
+  rejection of terminators removed from generated input. The
+  `EXPRESSIR_CONFORMANCE=1` tier round-trips the full stepmod resource
+  slice (<250 KB; 266 files on this box) and `rake conformance` runs it; the
+  nightly `conformance.yml` workflow checks out the sparse stepmod
+  corpus. En route the generator found a formatter bug: nested unary
+  minus formatted as `--x`, which EXPRESS reads as a comment; unary
+  operands are now parenthesized. Generator lesson: relational
+  operators are non-associative, and reserved words (e.g. `VALUE`)
+  cannot name parameters.
+- Part 3 (G.1.7 closure): the BASED_ON enumeration-chain example is in
+  `shtolo_annex_g_rule_audit_spec.rb`; every Annex G rule now has a
+  live worked example and the audit table has no unaudited tail.

data/TODO.sota/04-lsp.md

@@ -0,0 +1,70 @@
+# 04 — LSP + incremental platform
+
+Make Expressir IDE-grade. The resolution/checking machinery is the
+hard part and it exists; this task wires it to a language server.
+
+## Parts (each ships)
+
+1. Scaffold: `expressir-lsp` (solo binary or gem — decide by the
+   metanorma toolchain's needs) speaking stdio LSP 3.17: initialize,
+   diagnostics push, document symbols.
+2. Diagnostics: Checker notes as publishDiagnostics with model-node
+   → LSP range mapping (NodePositionIndex exists).
+3. Navigation: definition (ScopeResolver + the USE/REFERENCE ladder +
+   alias map), references, document/rename — rename updates the
+   model in place and re-emits via the Formatter (the compare/patch
+   engine provides the structural diff safety net).
+4. Hover: PrettyFormatter excerpt of the target declaration + its
+   remarks.
+5. Incremental: document-open/parse via the expressir-rs core path
+   when available (parsanol incremental machinery); fallback full
+   reparse. Cold-open target: SRL-scale schema set interactive on
+   this box.
+
+## Acceptance
+
+- A live editor session on the stepmod corpus: diagnostics on open,
+  go-to-definition across a USE ladder, rename across two schemas
+  with the diff verified by SchemaCompare.
+
+## Status: done
+
+- Part 1 (scaffold): `exe/expressir-lsp` ships in the gem
+  (`executables`), speaking JSON-RPC 2.0 over stdio with LSP 3.17
+  framing (`Content-Length`), lifecycle (initialize/shutdown/exit) and
+  full-sync text documents (didOpen/didChange/didSave/didClose).
+  `Expressir::Lsp::{Document,Workspace,Server}` are autoloaded from
+  `lib/expressir/lsp.rb`.
+- Part 2 (diagnostics): `Workspace#diagnostics` runs the Checker over
+  the open documents, maps notes through NodePositionIndex/LineMap to
+  byte→UTF-16 ranges, and publishes `textDocument/publishDiagnostics`.
+  Parse failures publish a diagnostic at the reported line/char and
+  keep the last good tree for navigation. Cross-document unresolved
+  notes are suppressed when another open document supplies the
+  referenced schema or interfaced declaration (the checker sees one
+  file at a time).
+- Part 3 (navigation): definition resolves declaration tokens,
+  local references, the USE/REFERENCE ladder and its alias map
+  (`colour AS hue` jumps to `colour`); references walks every open
+  document and interface item; rename computes minimal edits for the
+  declaration and every reference across schemas, then applies them in
+  memory, verifies each document reparses, runs SchemaCompare to
+  reject any removal other than the renamed declaration, and re-emits
+  the renamed schema through the Formatter to prove it formats. Rename
+  keeps aliases untouched: only the imported name at the interface
+  item and usages written with the original name change.
+- Part 4 (hover): `Express::PrettyFormatter` excerpt in a markdown
+  `express` code fence (remarks included by the formatter).
+- Part 5 (incremental): changes reparse through the native/core parser
+  path; identical text is a no-op and checker results are memoized
+  across requests for the same document set. There is no incremental
+  parse API in the expressir-rs core to call, so true content-
+  incremental reparse remains a measured gap: cold open of the 186 KB
+  geometric_model_schema on this loaded box takes ~9.4 s (document
+  parse) and ~0.03 s for the symbol index. Recorded for an
+  expressir-rs incremental API when it exists; semantics stay Ruby.
+- Specs: `spec/expressir/lsp/document_spec.rb` (positions, UTF-16,
+  tokens, symbols, parse-failure retention) and
+  `spec/expressir/lsp/server_spec.rb` (capabilities, diagnostics,
+  symbols, USE/alias definition, references, hover, cross-schema
+  rename verified by SchemaCompare and Formatter) — 14 examples.

data/TODO.sota/05-interop.md

@@ -0,0 +1,55 @@
+# 05 — Interop exports: EXPRESS as a source
+
+Expressir as the interchange point between EXPRESS and the rest of the
+modeling world. These mappings are contributions (no ISO mapping
+exists) — every decision is documented in the output module's docs.
+
+## Parts (each ships)
+
+1. JSON Schema export: entities → object schemas (attribute order,
+   OPTIONAL → nullable, aggregates → arrays with bounds where
+   expressible, SELECT → anyOf, ENUM → enum). Subtype handling: the
+   closure flattened into allOf groups. Documented decisions file.
+2. OWL/RDF export: the ifcOWL lineage generalized to arbitrary
+   EXPRESS — entities → classes, supertype closure → subclass axes,
+   attributes → properties with domain/range from the model, SELECT
+   → union semantics, WHERE rules NOT exported (documented scope
+   limit). Cite ifcOWL/EXPRESS→OWL literature in the decisions file.
+3. Optional tier: UML/XMI export.
+
+## Acceptance
+
+- Export the SRL corpus; a consumer round-trip (validate exported
+  JSON Schema against a Part 21-derived JSON serialization of the
+  Annex H population).
+
+## Status: done
+
+- Part 1 (JSON Schema): `Expressir::Interop::JsonSchema` renders a
+  schema as JSON Schema 2020-12 — entities as object definitions
+  composed with `allOf` over `SUBTYPE OF` parents, explicit attributes
+  in declaration order, OPTIONAL attributes nullable and out of
+  `required`, aggregates as arrays with declared bounds, SELECT as
+  `anyOf` (BASED_ON folded), ENUMERATION as a string enum (BASED_ON
+  folded), defined types through to their underlying primitive.
+  Derived/inverse attributes, WHERE/UNIQUE rules and constants are
+  documented exclusions. CLI: `expressir export-json-schema`.
+  Decisions: `docs/_guides/interop/json-schema.adoc`.
+- Part 2 (OWL/RDF): `Expressir::Interop::Owl` renders Turtle — entities
+  as `owl:Class` with `rdfs:subClassOf` per supertype, explicit
+  attributes as object/datatype properties with domain and range,
+  SELECT as an `owl:unionOf` equivalent class, ENUMERATION items as
+  individuals, primitive defined types as `rdfs:Datatype` with XSD
+  equivalences; aggregates range over `rdf:List`. WHERE/UNIQUE bodies,
+  cardinalities and aggregate bounds are documented scope limits. CLI:
+  `expressir export-owl`. Decisions and the ifcOWL lineage citations:
+  `docs/_guides/interop/owl-rdf.adoc`.
+- Part 3 (UML/XMI): explicitly the optional tier; not shipped.
+- Acceptance: the Annex H population is serialized to JSON in Part 21
+  slot order (supertype attributes first, `$`/`*` null, references
+  expanded with a cycle guard) and validated against the exported
+  entity definitions with an independent consumer validator in
+  `spec/expressir/interop/json_schema_spec.rb` — 13 instances, zero
+  errors; dropping a required attribute fails. A gated
+  `EXPRESSIR_CONFORMANCE` tier exports every schema in the stepmod
+  resource slice (<250 KB; >200 schemas).

data/TODO.sota/06-dialects.md

@@ -0,0 +1,57 @@
+# 06 — Dialect awareness
+
+EXPRESS the standard has editions; Expressir should speak them
+explicitly.
+
+## Parts (each ships)
+
+1. Dialect flag: parser + checker accept `dialect: :"10303-11:1994" |
+   :"10303-11:2004"` (default 2004). Gating: EXTENSIBLE/BASED_ON/
+   GENERIC_ENTITY are 2004-only (1994 corpora exist in legacy
+   resources); 1994 rejects them with a dialect note, 2004 accepts.
+2. Amendment tracking: the Amd1 change list as a source document;
+   edition-sensitive checker notes (`:check_dialect_*`).
+3. Corpus pass: run both dialects over the resource slice; mixed
+   dialects in one file produce a clear diagnostic.
+
+## Acceptance
+
+- A 1994-era resource schema parses clean under 1994, flags its
+  non-1994 constructs under 2004-diagnostics mode.
+
+## Status: done
+
+- Part 1 (dialect flag): `Expressir::Express::Dialect` normalizes the
+  `:"10303-11:1994"` / `:"10303-11:2004"` editions (also "1994",
+  "2004", full strings) and rejects anything else with
+  `InvalidOptionError`. `Parser.from_file/from_files/from_exp` accept
+  `dialect:` (default 2004) and validate it; the grammar parses the
+  union of both editions so a model can be inspected under either.
+  `Checker.new(repository, dialect:)` emits the edition notes:
+  under 1994, `:check_dialect_2004_only` (error) for EXTENSIBLE,
+  BASED_ON, GENERIC_ENTITY and SUBTYPE_CONSTRAINT declarations; under
+  2004, `:check_dialect_deprecated` (warning) for the edition-1 inline
+  subtype-constraint syntax that Annex K deprecates in favour of
+  SUBTYPE_CONSTRAINT. Notes are emitted only when a dialect is passed,
+  so the default checker report is unchanged.
+- Part 2 (amendment tracking): the audited change list is a checked-in
+  source document at
+  `spec/fixtures/dialects/iso-10303-11-2004-changes.yaml`, with the
+  clause each construct comes from (8.4.1, 8.4.2, clause 9, Annex K,
+  Annex G) and a live example per entry.
+  `spec/expressir/express/dialect_spec.rb` asserts every change entry's
+  declared note fires under 1994 (or 2004 for the deprecated syntax),
+  that no note id is outside `Dialect::NOTE_IDS`, and that the 2004
+  examples are accepted under 2004. A 1994-era plain schema produces
+  no notes under either dialect.
+- Part 3 (corpus pass): a gated `EXPRESSIR_CONFORMANCE` tier runs both
+  dialects over the stepmod resource slice (266 files <250 KB), and
+  `:check_dialect_mixed` gives one clear diagnostic when a file
+  combines 2004-only declarations with edition-1 inline
+  subtype-constraint syntax. Installations without the corpus skip the
+  tier.
+- Limitation recorded: the 2004 text grammar is effectively a superset
+  of 1994, so the only edition-1-only signals available to a text
+  checker are the Annex K deprecations; EXPRESS-G notation and the
+  enumeration-ordering semantics deprecated by Annex K have no text
+  form to flag.

data/TODO.sota/07-reference-artifacts.md

@@ -0,0 +1,55 @@
+# 07 — Reference artifacts: the citable Expressir
+
+The academic endgame — make the implementation provable and citable.
+
+## Parts (each ships)
+
+1. Grammar cross-walk: rule-by-rule table, parsanol grammar rule ↔
+   ISO 10303-11 Annex A/B production, with divergences (extensions,
+   recoveries) classified — rendered into docs/ and kept in sync by a
+   spec that fails when a grammar rule lacks a row.
+2. Property-based corpus testing as a published nightly tier (03's
+   harness, trended: parse rate, diagnostic rate, idempotence rate).
+3. Published guides: one doc per subsystem (checker + note-id
+   catalog, shtolo + annex-g-rules linkage, p21, evaluator, lsp),
+   generated where possible from the model (note-id catalog from the
+   Checker's constants).
+
+## Acceptance
+
+- docs/ builds with the cross-walk and guides; the sync spec is part
+  of the default suite.
+
+## Status: done
+
+- Part 1 (grammar cross-walk): `Expressir::Reference::GrammarCrosswalk`
+  reads the audited mapping in
+  `lib/expressir/reference/grammar_crosswalk.yml` and renders
+  `docs/_guides/reference/grammar-crosswalk.adoc`. All 250 parsanol
+  rules are accounted for: 207 aligned with the same-named Annex A
+  production (CamelCase normalized to snake_case), 8 decomposed into
+  PEG sub-rules, 30 literal operator/delimiter tokens, 4 lexical
+  whitespace/delimiter rules and 1 PEG-internal keyword guard. The 12
+  Annex A productions without a dedicated rule are listed and
+  classified (remark productions are handled by
+  RemarkScanner/RemarkAttacher; the rest are PEG lookaheads or
+  character classes). The Annex A snapshot lives at
+  `spec/fixtures/reference/annex-ab-productions.txt`. The spec fails
+  when a grammar rule lacks a row, a row names a missing rule/status,
+  an Annex production is unaccounted for, or the published guide is
+  stale; regenerate with `rake reference:crosswalk`.
+- Part 2 (trended nightly tier): `Expressir::Conformance::Trend`
+  measures a corpus slice — file count, parse rate, format-idempotence
+  rate, diagnostic rate (Checker notes per parsed file), error/warning counts and per-note-id counts —
+  and writes a JSON artifact. `rake conformance:trend` runs it over the
+  stepmod resource slice; the nightly `conformance.yml` workflow runs
+  it after the round-trip tier and uploads `conformance-trend.json`.
+  Spec: `spec/expressir/conformance/trend_spec.rb`.
+- Part 3 (published guides): `docs/_guides/reference/` now carries an
+  index plus subsystem guides — checker (with the generated note-id
+  catalog, `rake reference:notes`), Part 21, SHTOLO/Annex G (linked to
+  `annex-g-rules.md` and the audit spec), evaluator, and the language
+  server. The two generated pages are checked for staleness by
+  `spec/expressir/reference/*_spec.rb`, which run in the default suite.
+  The docs site build (`.github/workflows/docs.yml`) covers the new
+  pages.

data/TODO.suma-improvements/07-part28-xml.md

@@ -1,15 +1,12 @@
-# 07 — Part 28 XML: select mapping v2 (#276)
+# 07 — Part 28 XML: select mapping v2 (#276) — DONE
 
-## Goal
-Full ISO 10303-28 EXPRESS-to-XML beyond the v1 skeleton
-(lib/expressir/express/xsd.rb): proper SELECT mapping (currently
-xs:anyType), aggregate/optional fidelity, schema-level structure.
+Shipped: the ISO 10303-28 SELECT mapping lives in
+lib/expressir/express/xsd.rb (complexType + xs:choice, entity members
+as global-element refs, defined-type members by name+type, extensible-
+empty fallback to sequence) and is covered by spec/expressir/express/
+xsd_spec.rb. The CLI exposes both halves: `expressir xsd` and
+`expressir xml-index` (#503).
 
-## Steps
-- ISO 10303-28 mapping rules for SELECT types (union/member semantics)
-- apply on top of xsd.rb's element/complexType generation
-- validate generated XSDs against the ISO 10303-28 conformance examples
-
-## Acceptance
-- a select-typed attribute renders per the standard (not xs:anyType)
-- the v1 examples still generate unchanged except where v2 improves them
+Remaining escalation (moved to parity-ee 17 scope): validating the
+generated XSDs against the Part 28 reference corpus — the detached
+docs carry the standard text only, not the reference XSDs.

data/docs/_guides/interop/index.adoc

@@ -0,0 +1,25 @@
+---
+title: Interop Exports
+nav_order: 12
+has_children: true
+---
+
+= Interop Exports
+
+== Purpose
+
+Expressir can render an EXPRESS schema into JSON Schema and OWL/RDF.
+No ISO mapping exists for either rendering: these are contributions of
+the Expressir project, and the decisions behind them are documented in
+the child guides so consumers can rely on stable semantics.
+
+== Commands
+
+[source,shell]
+----
+expressir export-json-schema path/to/schema.exp -o schema.json
+expressir export-owl path/to/schema.exp -o schema.ttl
+----
+
+The Ruby API is available as `Expressir::Interop::JsonSchema` and
+`Expressir::Interop::Owl`.

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).