suma 0.5.7 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98f57b1e48077074a8b282922f6b1196a718fc50bfae43d31fe81dad940d0092
-  data.tar.gz: 3c0982d9e700c84b6cfc9030d835cef3f2bd34ae3309df3ce622f25301124a11
+  metadata.gz: 54c10b8d56459f9d53cd1b5988cbcc2193675f4dffa43e115845400497faa8f9
+  data.tar.gz: b46df0c3ef57f69e2e0e5e3b7dfdf3c464189a66f372ef2a5f7a5d3a8d47b34b
 SHA512:
-  metadata.gz: 95856f79045ee2124742c28d86c18fe50401bbc642ad44872912b0e05e31713a9fb479601a18f0320810583f2a2ae1b5de2d5d897815668d56087f6078af7d90
-  data.tar.gz: d0514ee213feaed81c9f4d79ff10728634c60ba5c731cc9a2dc9adae64fa87d45ec7512c6697eb31c5de9efc9f75198449d90631d1a032c69e65833b3aee7bc3
+  metadata.gz: 51f6a6ed42abb76af7342d06e0b73c3132ddf7e65ffdb5d29c96892860fd3be534557581f6bd14b6dd15e022a8e2ac250cdb23f6ed4d68242457515b8951b415
+  data.tar.gz: c562c0691baa4b3fb708b94dd5853014a18e4bad0cd8527cbf7922a7273ebd982a5239ea13914c0d60f279e2ceae9b534a43a58ff42b339c7dd5114f7e5be576

data/.github/workflows/nightly-benchmark.yml

@@ -0,0 +1,25 @@
+name: nightly-benchmark
+
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Run synthetic corpus benchmark
+        run: bundle exec ruby bin/benchmark_corpus
+        env:
+          SUMA_BENCH_SCHEMAS: "1000"
+          SUMA_BENCH_MAX_SECONDS: "180"
+          SUMA_BENCH_MAX_RSS_MB: "2048"

data/.github/workflows/release-provenance.yml

@@ -0,0 +1,41 @@
+name: release-provenance
+
+on:
+  # Tag pushes reliably fan out (the release workflow pushes v* tags with a
+  # PAT); release-published events created by CI tokens may not.
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  # Keyless sigstore signing exchanges this token for a short-lived certificate.
+  id-token: write
+
+jobs:
+  provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name || github.ref }}
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - uses: sigstore/cosign-installer@v3
+      - name: Build gem
+        run: gem build suma.gemspec
+      - name: Write, verify, and sign provenance
+        run: bundle exec ruby bin/release_provenance
+        env:
+          SUMA_PROVENANCE_SIGN: sigstore
+      - name: Independent sha256 pass
+        run: sha256sum *.gem provenance.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-provenance
+          path: |
+            provenance.json
+            provenance.json.bundle

data/.rubocop_todo.yml

@@ -116,6 +116,11 @@ Lint/UnusedMethodArgument:
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'bin/benchmark_corpus'
+    - 'lib/suma/worker_pool.rb'
+    - 'spec/suma/reproducibility_spec.rb'
+    - 'lib/suma/cli/resolve.rb'
+    - 'lib/suma/urn_resolver.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
     - 'lib/suma/cli/core.rb'
     - 'lib/suma/jsdai/figure.rb'
@@ -131,18 +136,27 @@ Metrics/AbcSize:
     - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
     - 'lib/suma/term_extractor.rb'
     - 'lib/suma/thor_ext.rb'
+    - 'lib/suma/closure_validator.rb'
+    - 'lib/suma/corpus_graph.rb'
+    - 'lib/suma/change_manifest.rb'
+    - 'lib/suma/cli/generate_register.rb'
+    - 'lib/suma/owl_projection.rb'
+    - 'lib/suma/cli/export.rb'
 
 # Offense count: 2
 # Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Exclude:
+    - 'bin/benchmark_corpus'
     - 'lib/suma/term_extractor.rb'
 
 # Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
+    - 'lib/suma/worker_pool.rb'
+    - 'lib/suma/urn_resolver.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
     - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/express_schema.rb'
@@ -151,11 +165,19 @@ Metrics/CyclomaticComplexity:
     - 'lib/suma/schema_comparer.rb'
     - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
     - 'lib/suma/thor_ext.rb'
+    - 'lib/suma/closure_validator.rb'
+    - 'lib/suma/owl_projection.rb'
 
 # Offense count: 32
 # Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Exclude:
+    - 'bin/benchmark_corpus'
+    - 'lib/suma/cli/build.rb'
+    - 'lib/suma/worker_pool.rb'
+    - 'lib/suma/provenance.rb'
+    - 'lib/suma/cli/resolve.rb'
+    - 'lib/suma/urn_resolver.rb'
     - 'spec/**/*'
     - 'lib/suma/cli/check_svg_quality.rb'
     - 'lib/suma/cli/core.rb'
@@ -172,23 +194,35 @@ Metrics/MethodLength:
     - 'lib/suma/staged_collection_builder.rb'
     - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
     - 'lib/suma/term_extractor.rb'
+    - 'lib/suma/closure_validator.rb'
+    - 'lib/suma/cli/validate.rb'
+    - 'lib/suma/cli/generate_register.rb'
+    - 'lib/suma/owl_projection.rb'
+    - 'lib/suma/cli/export.rb'
 
 # Offense count: 3
 # Configuration parameters: Max, CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Exclude:
+    - 'lib/suma/processor.rb'
+    - 'lib/suma/express_schema.rb'
+    - 'lib/suma/term_extractor.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
     - 'lib/suma/link_validator.rb'
     - 'lib/suma/register_manifest_generator.rb'
+    - 'lib/suma/closure_validator.rb'
 
 # Offense count: 4
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
+    - 'lib/suma/worker_pool.rb'
     - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure_image.rb'
     - 'lib/suma/schema_comparer.rb'
     - 'lib/suma/svg_quality/formatters/terminal_formatter.rb'
+    - 'lib/suma/closure_validator.rb'
+    - 'lib/suma/owl_projection.rb'
 
 # Offense count: 1
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
@@ -225,6 +259,15 @@ RSpec/ContextWording:
 # Configuration parameters: Max, CountAsOne.
 RSpec/ExampleLength:
   Exclude:
+    - 'spec/suma/schema_cache_spec.rb'
+    - 'spec/suma/worker_pool_spec.rb'
+    - 'spec/suma/schema_collection_rebuild_targets_spec.rb'
+    - 'spec/suma/build_plan_spec.rb'
+    - 'spec/suma/reproducibility_spec.rb'
+    - 'spec/suma/provenance_spec.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+    - 'spec/suma/cli/resolve_spec.rb'
+    - 'spec/suma/urn_resolver_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli/extract_terms_spec.rb'
     - 'spec/suma/cli/generate_register_spec.rb'
@@ -232,7 +275,11 @@ RSpec/ExampleLength:
     - 'spec/suma/cli/reformat_spec.rb'
     - 'spec/suma/cli_spec.rb'
     - 'spec/suma/collection_config_spec.rb'
+    - 'spec/suma/closure_validator_spec.rb'
     - 'spec/suma/collection_manifest_spec.rb'
+    - 'spec/suma/corpus_graph_spec.rb'
+    - 'spec/suma/owl_projection_spec.rb'
+    - 'spec/suma/schema_profile_spec.rb'
     - 'spec/suma/eengine_converter_spec.rb'
     - 'spec/suma/express_reformatter_spec.rb'
     - 'spec/suma/express_schema_spec.rb'
@@ -242,6 +289,8 @@ RSpec/ExampleLength:
     - 'spec/suma/link_validator_spec.rb'
     - 'spec/suma/manifest_traverser_spec.rb'
     - 'spec/suma/note_processor_spec.rb'
+    - 'spec/suma/publication_spec.rb'
+    - 'spec/suma/owl_projection_spec.rb'
     - 'spec/suma/processor_spec.rb'
     - 'spec/suma/register_manifest_generator_spec.rb'
     - 'spec/suma/schema_category_spec.rb'
@@ -256,6 +305,9 @@ RSpec/ExampleLength:
     - 'spec/suma/term_classification_spec.rb'
     - 'spec/suma/term_extractor_spec.rb'
     - 'spec/suma/urn_spec.rb'
+    - 'spec/suma/change_classification_spec.rb'
+    - 'spec/suma/change_manifest_spec.rb'
+    - 'spec/suma/change_impact_spec.rb'
 
 # Offense count: 4
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
@@ -286,6 +338,13 @@ RSpec/MessageSpies:
 # Configuration parameters: Max.
 RSpec/MultipleExpectations:
   Exclude:
+    - 'spec/suma/schema_cache_spec.rb'
+    - 'spec/suma/worker_pool_spec.rb'
+    - 'spec/suma/reproducibility_spec.rb'
+    - 'spec/suma/provenance_spec.rb'
+    - 'spec/suma/term_extractor_spec.rb'
+    - 'spec/suma/cli/resolve_spec.rb'
+    - 'spec/suma/urn_resolver_spec.rb'
     - 'spec/suma/cli/build_spec.rb'
     - 'spec/suma/cli/export_spec.rb'
     - 'spec/suma/cli/expressir_spec.rb'
@@ -293,7 +352,11 @@ RSpec/MultipleExpectations:
     - 'spec/suma/cli/reformat_spec.rb'
     - 'spec/suma/cli_spec.rb'
     - 'spec/suma/collection_config_spec.rb'
+    - 'spec/suma/closure_validator_spec.rb'
     - 'spec/suma/collection_manifest_spec.rb'
+    - 'spec/suma/corpus_graph_spec.rb'
+    - 'spec/suma/owl_projection_spec.rb'
+    - 'spec/suma/schema_profile_spec.rb'
     - 'spec/suma/eengine_converter_spec.rb'
     - 'spec/suma/eengine_spec.rb'
     - 'spec/suma/express_reformatter_spec.rb'
@@ -304,6 +367,8 @@ RSpec/MultipleExpectations:
     - 'spec/suma/link_validator_spec.rb'
     - 'spec/suma/manifest_traverser_spec.rb'
     - 'spec/suma/note_processor_spec.rb'
+    - 'spec/suma/publication_spec.rb'
+    - 'spec/suma/owl_projection_spec.rb'
     - 'spec/suma/processor_spec.rb'
     - 'spec/suma/register_manifest_generator_spec.rb'
     - 'spec/suma/schema_category_spec.rb'
@@ -312,12 +377,16 @@ RSpec/MultipleExpectations:
     - 'spec/suma/schema_discovery_spec.rb'
     - 'spec/suma/schema_exporter_spec.rb'
     - 'spec/suma/schema_index_spec.rb'
+    - 'spec/suma/schema_naming_spec.rb'
     - 'spec/suma/schema_template_spec.rb'
     - 'spec/suma/site_config/config_spec.rb'
     - 'spec/suma/staged_collection_builder_spec.rb'
     - 'spec/suma/svg_quality/scanner_spec.rb'
     - 'spec/suma/term_classification_spec.rb'
     - 'spec/suma/term_extractor_spec.rb'
+    - 'spec/suma/change_classification_spec.rb'
+    - 'spec/suma/change_manifest_spec.rb'
+    - 'spec/suma/change_impact_spec.rb'
 
 # Offense count: 3
 # Configuration parameters: Max, AllowedGroups.
@@ -328,6 +397,10 @@ RSpec/NestedGroups:
 # Offense count: 1
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/suma/reproducibility_spec.rb'
+
 RSpec/SpecFilePathFormat:
   Exclude:
     - '**/spec/routing/**/*'
@@ -337,3 +410,14 @@ RSpec/SpecFilePathFormat:
 RSpec/StubbedMock:
   Exclude:
     - 'spec/suma/schema_comparer_integration_spec.rb'
+
+# Offense count: 2
+# Configuration parameters: Max.
+RSpec/MultipleMemoizedHelpers:
+  Exclude:
+    - 'spec/suma/provenance_spec.rb'
+    - 'spec/suma/worker_pool_spec.rb'
+    - 'spec/suma/schema_cache_spec.rb'
+    - 'spec/suma/urn_resolver_spec.rb'
+    - 'spec/suma/register_manifest_generator_spec.rb'
+    - 'spec/suma/owl_projection_spec.rb'

data/CLAUDE.md

@@ -23,15 +23,47 @@ rspec spec/path/to_spec.rb:42  # Run a single test at line 42
 
 ```bash
 exe/suma build METANORMA_YAML                          # Build collection from site manifest
+exe/suma build METANORMA_YAML --incremental --jobs 4   # Re-render changed schemas + dependents; parallel export
+SUMA_SCHEMA_CACHE_DIR=.suma-cache exe/suma build METANORMA_YAML  # Reuse parsed models/outputs across builds
+rake benchmark                                         # 1,000-schema synthetic corpus budget check
+exe/suma build METANORMA_YAML --provenance provenance.json  # sha256 of inputs/outputs + toolchain
+exe/suma build METANORMA_YAML --provenance provenance.json --sign sigstore  # optional signature (minisign|sigstore)
 exe/suma export -o OUTPUT_DIR schema1.yml schema2.exp  # Export schemas (YAML manifest or .exp files)
+exe/suma export -o OUTPUT_DIR --publication AP_LEADER_ID schemas.yaml  # Export an AP publication bundle (lead + USE-FROM closure)
+exe/suma export --format owl -o OUT --urn BASE schemas.yaml  # Project the corpus to OWL/Turtle (one file per schema; add --corpus for a corpus ontology)
 exe/suma compare TRIAL_SCHEMA REFERENCE_SCHEMA -v VER  # Compare schemas, generate .changes.yaml
+exe/suma compare ... -v VER --typed-output FILE --changelog --impact --manifest SCHEMAS_YAML  # Typed change manifest, changelog, impact analysis
 exe/suma reformat PATH                                  # Reformat EXP files (use -r for recursive)
 exe/suma generate-schemas METANORMA_YAML SCHEMAS_YAML  # Generate schema manifest from site manifest
 exe/suma extract-terms SCHEMA_YAML GLOSSARIST_DIR -u URN   # Extract EXPRESS entity concepts to Glossarist v3 format
+exe/suma extract-terms ... --edition 3 --language-codes fra deu  # Provenance + linked localizations
+exe/suma resolve URN --manifest SCHEMAS_YAML --concepts DIR --register register.yaml -o OUT  # Emit canonical JSON + HTML
+exe/suma resolve --all --manifest SCHEMAS_YAML --concepts DIR --register register.yaml -o OUT  # Emit every URN artifact
 exe/suma generate-register SCHEMA_YAML OUT_DIR -u URN --id ID --ref REF  # Generate hierarchical register.yaml from schema manifest
 exe/suma validate links SCHEMAS_FILE DOCS_PATH          # Validate EXPRESS cross-reference links
+exe/suma validate closure SCHEMAS_MANIFEST [DOCUMENTS_PATH]  # Referential closure: every reference resolves (exit 1 on violations)
 ```
 
+## Schema profiles
+
+Suma works with any schema collection. `Suma::SchemaProfile` declares how schema
+identifiers and paths map to types (`ExpressSchema::Type`), how
+identifiers become display names (`SchemaNaming`), and the ordered
+register categories (`SchemaCategory`). Registered profiles: `iso10303`
+(default; STEP conventions incl. `/applications/` → application
+protocol) and `generic` (no STEP conventions). The CLI takes
+`--profile` on `export`, `extract-terms`, and `generate-register`.
+
+## ISO 10303 AP publications
+
+An AP publication is a lead schema (the AP's ARM/MIM) bundled with the
+module/resource schemas it USEs. `Suma::Publication` computes the
+transitive USE-FROM/REFERENCE closure from the parsed EXPRESS interfaces
+and resolves it against a schema manifest; `export --publication ID`
+writes the bundle flat under `<output>/<lead_id>/`. In the register,
+the "Application Protocols" category groups each AP's ARM/MIM under a
+per-publication parent section.
+
 ## Architecture
 
 ### Core pipeline (build command)
@@ -59,6 +91,15 @@ exe/suma validate links SCHEMAS_FILE DOCS_PATH          # Validate EXPRESS cross
 - **`ManifestTraverser`** — tree-walking service over a `CollectionManifest` (`find_schemas_only`, `export_schema_config`, `expand_schemas_only`, `remove_schemas_only_sources`)
 - **`SchemaDiscovery`** — schema-config I/O service on a single manifest node (`load_config` from `schemas.yaml`, `build_doc_entries`, `build_added_manifest`)
 - **`SchemaIndex`** — O(1) lookup index for schema and element names, used by `LinkValidator`
+- **`ChangeClassification` / `ChangeManifest` / `ChangeImpact`** — S3 typed change ontology: eengine actions are classified (additive/compatible/breaking/editorial), the typed manifest (`change-entry` records via lutaml-model) is emitted alongside `.changes.yaml` with a markdown changelog, and impact analysis walks `CorpusGraph#dependents_of` to report affected schemas and AP publications
+- **`CorpusGraph`** — the declared-element graph of a whole schema collection: schemas, declared elements, USE/REFERENCE interface edges; the resolution substrate for `ClosureValidator` (and later change-impact/incremental builds)
+- **`ClosureValidator`** — S1 referential closure: extracts every EXPRESS-internal reference (attribute domains, SELECT/aggregate branches, where-rule expressions, subtype constraints, supertype/subtype lists, rule applies-to, interfaces) and resolves it against a `CorpusGraph`; zero violations is the corpus well-formedness gate (`rake closure`)
+- **`OwlProjection`** — S2 formal semantics: projects a parsed corpus into OWL/Turtle. Entities → `owl:Class`; `SUBTYPE OF` → `rdfs:subClassOf`; SELECT → `owl:unionOf`; enums → `owl:oneOf` named individuals; simple type aliases → `rdfs:Datatype`; explicit/derived/inverse attributes → object/datatype properties attached through named `owl:Restriction` nodes (cardinality from optionality and aggregate bounds); WHERE rules and DERIVE/INVERSE clauses → annotated (`rdfs:comment`) constraints. IRIs come from `Urn` (`<base>:tech:<schema>.<element>`), per-schema ontologies declare `owl:imports` for their `USE FROM`/`REFERENCE` targets, and the corpus ontology imports every schema. `#validate` checks materialization, property declarations, orphan classes, and superclass acyclicity. Output contains no blank nodes, so projections are deterministic and golden-comparable
+- **`SchemaCache`** — content-addressed on-disk store for generated `.exp` output and parsed Expressir repositories. Keys compose source bytes with the Expressir version (plus Suma/Marshal versions for parsed entries), so a hit is equivalent to a fresh build. Enabled by `SUMA_SCHEMA_CACHE_DIR`; hit/miss counters expose parse reuse. **`NullCache`** is the disabled-mode null object
+- **`BuildPlan`** — incremental-build decision: hashes every schema source, diffs against the persisted state, and expands changed schemas to their transitive dependents through `CorpusGraph`. State defaults to `plain_schemas/.suma-build-state.json`; `SchemaCollection#rebuild_targets` is the build-facing query
+- **`WorkerPool`** — bounded worker pool for independent per-schema work. Schema export runs in the pool (`build --jobs N`); Metanorma document compilation stays sequential and composes with `StagedCollectionBuilder`'s process isolation
+- **`UrnResolver`** — S4 dereferenceable identity: resolves `tech:` schema/element URNs from a manifest, `term:` concept URNs from Glossarist documents, and the dataset URN from `register.yaml`; emits canonical JSON plus a static HTML document per URN at a path derived from the URN itself. Every URN the register emits resolves against the artifact set
+- **`Provenance`** — S5 build provenance: sha256 of every input and output (files or directory trees) plus Ruby/Expressir/Suma toolchain versions, written as canonical JSON by `build --provenance FILE`. `Provenance.verify` recomputes the digests independently; `build --sign minisign|sigstore` (with `--sign-key` where needed) optionally signs the manifest, and `bin/release_provenance` signs keylessly with cosign in the release workflow (`SUMA_PROVENANCE_SIGN`)
 - **`LinkValidator`** — validates EXPRESS cross-reference links against a `SchemaIndex`; returns `LinkValidationResult` structs for unresolved links
 
 ### CLI structure
@@ -74,6 +115,8 @@ The `extract-terms` command reads an EXPRESS schema manifest, parses each `.exp`
 - Entity remarks processed into notes (first-sentence extraction, redundant note removal, invalid reference filtering)
 - Domain classification via `ExpressSchema::Type` (resource vs application module)
 - Section references for hierarchical grouping
+- Provenance on every concept: the source schema citation, the entity URN under `sourced_from`, and the owning edition/version
+- Linked localizations: `--language-codes` emits additional `localizations` of the same managed concept (same stable UUID, per-language localized UUIDs); the text is the source-language content until translations are supplied
 
 The `generate-register` command reads the same schema manifest and emits `register.yaml` with hierarchical sections:
 - Top-level groups: Resources (133) before Application Modules (1123)
@@ -86,6 +129,7 @@ The `generate-register` command reads the same schema manifest and emits `regist
 - **metanorma** — document compilation (`.adoc` → XML/HTML/PDF)
 - **lutaml-model** — YAML/XML model serialization (used in `SiteConfig`, `CollectionConfig`)
 - **glossarist** — term extraction output format
+- **rdf / rdf-turtle** — OWL projection serialization (already required through glossarist; no direct gemspec entry)
 - **eengine** (optional, external binary) — schema comparison via `Eengine::Wrapper`
 
 ### Schema comparison flow

data/README.adoc

@@ -14,12 +14,18 @@ to build the following artifacts:
 
 == Features
 
-* EXPRESS schema management for STEP standards
+* EXPRESS schema management for STEP and other schema collections
 * Document collection building and compilation
+* Referential closure validation over the whole corpus
 * EXPRESS links validation and extraction
 * Schema listing file generation
+* OWL/Turtle projection with structural validation
+* Typed change manifests, changelogs, and dependency impact analysis
+* Glossarist terminology and hierarchical registers with edition metadata
+* Dereferenceable URN artifacts (canonical JSON + static HTML)
+* Incremental, parallel, and cached corpus builds
+* Reproducible outputs with verifiable, optionally signed provenance
 * Integration with the Metanorma ecosystem
-* Progress tracking for schema loading operations
 
 == Installation
 
@@ -37,13 +43,16 @@ $ gem install suma
 # Defaults to `suma help`
 $ suma
  Commands:
-  suma build METANORMA_SITE_MANIFEST                                  # Build collection specified in site manifest (`metanorma*.yml`)
-  suma convert-jsdai XML_FILE IMAGE_FILE OUTPUT_DIR                   # Convert JSDAI XML and image files to SVG and EXP files
-  suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract EXPRESS entity concepts into Glossarist v3 format
-  suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH            # Generate hierarchical register.yaml from schema manifest
-  suma generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE  # Generate EXPRESS schema manifest file from Metanorma site manifest
-  suma help [COMMAND]                                                 # Describe available commands or one specific command
+  suma build METANORMA_SITE_MANIFEST                                  # Build collection from site manifest
+  suma check_svg_quality [PATH]                                       # Check SVG quality
+  suma compare TRIAL_SCHEMA REFERENCE_SCHEMA                          # Compare schemas; typed changes, impact
+  suma convert-jsdai XML_FILE IMAGE_FILE OUTPUT_DIR                   # Convert JSDAI XML and image files to SVG and EXP
+  suma export *FILES -o OUTPUT                                        # Export EXPRESS schemas or project them to OWL
+  suma extract-terms SCHEMA_MANIFEST_FILE GLOSSARIST_OUTPUT_PATH      # Extract entity concepts to Glossarist v3
+  suma generate-register SCHEMA_MANIFEST_FILE OUTPUT_PATH             # Generate hierarchical register.yaml
+  suma generate-schemas METANORMA_MANIFEST_FILE SCHEMA_MANIFEST_FILE  # Generate a schema manifest from a site manifest
   suma reformat EXPRESS_FILE_PATH                                     # Reformat EXPRESS files
+  suma resolve [URN] --manifest=MANIFEST -o OUTPUT                    # Emit canonical JSON + HTML for URNs
   suma validate SUBCOMMAND ...ARGS                                    # Validate express documents
 ----
 
@@ -65,6 +74,13 @@ Options:
 
 `--[no-]compile`:: Compile or skip compilation of collection (default: true)
 `--schemas-all-path=PATH`, `-s PATH`:: Generate file that contains all schemas in the collection
+`--[no-]staged`:: Memory-bounded build: compile each member in its own process, then reinflate
+`--[no-]incremental`:: Re-render only changed schemas and their transitive dependents
+`--state-file=PATH`:: Incremental build state file (default: `plain_schemas/.suma-build-state.json`)
+`--jobs=N`:: Concurrent schema export workers (document compilation stays sequential; default: 1)
+`--provenance=PATH`:: Write a provenance manifest (sha256 of inputs/outputs + toolchain versions)
+`--sign=METHOD`:: Sign the provenance manifest: `minisign` or `sigstore`
+`--sign-key=PATH`:: Signing key; minisign requires it, sigstore signs keylessly when omitted
 
 The generated `schemas-*.yaml` file name is derived from the input file name
 with the word `metanorma` replaced with `schemas`.
@@ -141,6 +157,7 @@ $ suma validate SUBCOMMAND [options]
 Subcommands:
 
 `links`:: Validate EXPRESS links
+`closure`:: Validate referential closure over the whole corpus
 
 ==== Links subcommand
 
@@ -176,6 +193,23 @@ This command:
 * Writes validation results to the `OUTPUT_FILE`
 * Provides progress bars to track schema loading and link validation
 
+==== Closure subcommand
+
+The `closure` subcommand extracts every EXPRESS-internal reference (attribute
+domains, SELECT and aggregate branches, where-rule expressions, subtype
+constraints, supertype/subtype lists, rule applies-to, and USE/REFERENCE
+interfaces) and resolves it against the corpus graph. It exits non-zero when
+any reference does not resolve, which makes it usable as a CI gate
+(`rake closure` runs it on the fixture corpus).
+
+[source,sh]
+----
+$ suma validate closure SCHEMAS_MANIFEST [DOCUMENTS_PATH] [--format terminal|json|yaml]
+----
+
+When `DOCUMENTS_PATH` is given, documentation-layer link failures are merged
+into the same report.
+
 
 === Generate schemas command
 
@@ -225,7 +259,7 @@ used for other EXPRESS schema collections that require term extraction for
 glossary or dictionary applications.
 
 The `suma extract-terms` command extracts terms from EXPRESS schemas and
-generates a Glossarist v2 dataset in the output directory. This command processes
+generates a Glossarist v3 dataset in the output directory. This command processes
 various types of STEP schemas and creates standardized terminology datasets
 suitable for glossary and dictionary applications.
 
@@ -239,12 +273,14 @@ Parameters:
 `SCHEMA_MANIFEST_FILE`:: Path to the schema manifest file that lists all schemas
 to process (e.g., "schemas-smrl-all.yml")
 
-`GLOSSARIST_OUTPUT_PATH`:: Path to the output directory where the Glossarist v2
+`GLOSSARIST_OUTPUT_PATH`:: Path to the output directory where the Glossarist v3
 dataset will be generated
 
 Options:
 
 `--language_code`, `-l`:: Language code for the Glossarist dataset (default: "eng")
+`--edition=N`:: Owning edition recorded on each concept
+`--language-codes=a,b`:: Additional linked localization languages (the primary language is always included)
 
 ==== Supported schema types
 
@@ -275,7 +311,7 @@ information:
 
 ==== Output format
 
-The command generates a Glossarist v2 compliant dataset with:
+The command generates a Glossarist v3 compliant dataset with:
 
 * `concept/` directory containing concept definition files in YAML
 * `localized_concept/` directory containing localized concept files in YAML
@@ -326,6 +362,13 @@ Options:
 The wildcard is stripped for the base URN and kept in `urnAliases`.
 *Required*.
 
+`--year=N`:: Edition year recorded on the register
+
+`--supersedes=URN`:: URN/ref of the superseded edition
+
+`--edition=N`:: Edition number, tagged as `edition:N`; every register also
+carries a `dataset:<id>` tag so sibling editions can be grouped.
+
 The URN is fully configurable — every component can be changed to match the
 dataset being exported. The general structure is:
 
@@ -521,6 +564,11 @@ Options:
 `--[no-]annotations`:: Include annotations (remarks/comments) in exported schemas (default: false)
 
 `--[no-]zip`:: Create ZIP archive of exported schemas (default: false)
+`--profile=PROFILE`:: Schema profile: `iso10303` (default) or `generic`
+`--publication=SCHEMA_ID`:: Export an AP publication bundle: the lead schema plus its transitive USE-FROM/REFERENCE closure
+`--format=FORMAT`:: Output format: `express` (default) or `owl`
+`--[no-]corpus`:: OWL only: emit one corpus ontology importing every schema ontology
+`--urn=URN`:: OWL only: base URN for IRIs, before the `:tech` component
 
 ==== Behavior
 
@@ -639,6 +687,65 @@ express-files/
 ----
 
 
+=== Schema profiles and AP publications
+
+Suma works with any schema collection. `Suma::SchemaProfile` declares how
+schema identifiers and paths map to types, how identifiers become display
+names, and the ordered register categories. Registered profiles:
+
+`iso10303`:: Default; STEP conventions including `/applications/` classifying as an application protocol
+`generic`:: No STEP conventions (one category for every schema)
+
+An AP publication is a lead schema bundled with the module and resource
+schemas it USEs. `--publication SCHEMA_ID` computes the transitive
+USE-FROM/REFERENCE closure and writes the bundle flat under
+`OUTPUT/<lead_id>/`. In the register, application protocols are grouped under
+a per-publication parent section.
+
+=== OWL projection
+
+`suma export --format owl` projects a parsed corpus into OWL/Turtle:
+
+* entities become `owl:Class`; `SUBTYPE OF` becomes `rdfs:subClassOf`
+* SELECT types become `owl:unionOf`; enumerations become `owl:oneOf` named individuals
+* simple type aliases become `rdfs:Datatype`
+* explicit, derived, and inverse attributes become object/datatype properties attached through named `owl:Restriction` nodes, with cardinality from optionality and aggregate bounds
+* WHERE, DERIVE, and INVERSE clauses are preserved as annotated constraints
+
+IRIs derive from the corpus URN scheme (`<base>:tech:<schema>.<element>`).
+Per-schema ontologies declare `owl:imports` for their USE-FROM/REFERENCE
+targets, and `--corpus` adds a corpus ontology importing every schema. The
+projection is validated before writing (materialization, property
+declarations, orphan classes, dangling superclasses, superclass cycles), and
+contains no blank nodes, so it is deterministic and golden-comparable.
+
+[source,sh]
+----
+$ suma export --format owl --urn urn:iso:std:iso:10303:-2:ed-2:en \
+    -o OUTPUT schemas.yaml
+$ suma export --format owl --corpus --urn urn:iso:std:iso:10303:-2:ed-2:en \
+    -o OUTPUT schemas.yaml
+----
+
+=== Resolve URNs command
+
+The `resolve` command turns URNs into static, dereferenceable artifacts: a
+canonical JSON document (sorted keys) and an HTML page per URN, written under
+a path derived from the URN itself. It resolves:
+
+* `tech:` schema, declared-element, and attribute (OWL property) URNs from a schema manifest
+* `term:` concept URNs from Glossarist concept documents
+* the dataset URN from `register.yaml`
+
+[source,sh]
+----
+$ suma resolve URN --manifest SCHEMAS_YAML [--concepts DIR] [--register register.yaml] -o OUT
+$ suma resolve --all --manifest SCHEMAS_YAML [--concepts DIR] [--register register.yaml] -o OUT
+----
+
+`--all` also writes `index.html`, linking every artifact. No server is
+required.
+
 === Compare schemas command
 
 ==== General
@@ -667,6 +774,10 @@ Options:
 `--trial-stepmod=PATH`:: Override auto-detected trial repository root
 `--reference-stepmod=PATH`:: Override auto-detected reference repository root
 `--verbose`:: Enable verbose output
+`--typed-output=PATH`:: Write a typed change manifest (lutaml-model records with classification)
+`--[no-]changelog`:: Render a markdown changelog alongside the change manifest
+`--[no-]impact`:: Report affected schemas and AP publications using the corpus graph
+`--manifest=SCHEMAS_YAML`:: Schema manifest used for impact analysis
 
 ==== Typical workflow
 
@@ -1163,3 +1274,17 @@ Code-style rules enforced throughout `lib/suma/`:
 == Copyright and license
 
 Copyright Ribose. BSD 2-clause license.
+
+== Development and benchmarks
+
+The default gate is `rake` (specs, RuboCop, referential closure).
+
+[source,sh]
+----
+$ rake benchmark
+----
+
+`rake benchmark` builds a synthetic 1,000-schema corpus and asserts wall-time
+and peak-RSS budgets; the same benchmark runs nightly in CI. Schema export can
+run in parallel with `build --jobs N`, while Metanorma document compilation
+stays sequential and composes with staged process isolation.

data/Rakefile

@@ -9,4 +9,16 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+desc "Validate referential closure of the fixture corpora"
+task :closure do
+  # `ruby` (Rake helper) rather than `bundle exec exe/suma`: the latter
+  # does not resolve relative executables on Windows.
+  ruby "exe/suma validate closure spec/fixtures/ap_publication/schemas.yaml"
+end
+
+task default: %i[spec rubocop closure]
+
+desc "Benchmark a synthetic 1,000-schema corpus against time/memory budgets"
+task :benchmark do
+  ruby "bin/benchmark_corpus"
+end