suma 0.5.8 → 0.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3674c1699305e230eabb86ed343195cd0b6915c063b77b3b1fb540ce03a6e684
-  data.tar.gz: 8f86f1e113c3774de773261c96cab1292222be7e5ae97e9b463a2136c40aefce
+  metadata.gz: 01e0b1dd212172912b654cac481e0ce1eea1efee1275f45d4332c0a6bbb28e69
+  data.tar.gz: 54399e492be26b0a09595debdc61c256f566da28ed13ca002cae2a6eb0925b57
 SHA512:
-  metadata.gz: 60c730b7f8dc973837b72f6651877a74da259c5e887ee4429d9f884fd318192223dacd2a4be7b7631b9863b42c987fe642649cc89166f67ba343e33b78510db1
-  data.tar.gz: 6ad73db79afdc62625d6a11ce94a3759cbfdbeb74151fb6c8f89c9ca0105f372ead7f95fa36afd010a9244979612e9693712ed7a35c12789f6f64b8881aff692
+  metadata.gz: 9fb0aebf85233af1df6162efb518605bd7ab01c7396e7af6012144fd05c74a135ba7d2833b7bb633fa45c755e067d6799569412df0b21458b33d2730a5081a3a
+  data.tar.gz: d9836497a01e7711aece5c76534ecfa4e7e0876bfd414aab783ada288b1906e07a3f3b6994d17085f294b79a827c16ecb61bab7cf305a823b9527933e5aa7f1c

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

@@ -1,8 +1,11 @@
 name: release-provenance
 
 on:
-  release:
-    types: [published]
+  # 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:

data/.rubocop_todo.yml

@@ -116,9 +116,11 @@ Lint/UnusedMethodArgument:
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
     - 'bin/benchmark_corpus'
     - 'lib/suma/worker_pool.rb'
     - 'spec/suma/reproducibility_spec.rb'
+    - 'spec/suma/cli/build_integration_spec.rb'
     - 'lib/suma/cli/resolve.rb'
     - 'lib/suma/urn_resolver.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
@@ -155,6 +157,8 @@ Metrics/BlockLength:
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
+    - 'lib/suma/corpus_graph.rb'
     - 'lib/suma/worker_pool.rb'
     - 'lib/suma/urn_resolver.rb'
     - 'lib/suma/cli/check_svg_quality.rb'
@@ -172,6 +176,8 @@ Metrics/CyclomaticComplexity:
 # Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Exclude:
+    - 'lib/suma/artifact_server.rb'
+    - 'lib/suma/gcr_package.rb'
     - 'bin/benchmark_corpus'
     - 'lib/suma/cli/build.rb'
     - 'lib/suma/worker_pool.rb'
@@ -204,6 +210,7 @@ Metrics/MethodLength:
 # Configuration parameters: Max, CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
     - 'lib/suma/processor.rb'
     - 'lib/suma/express_schema.rb'
     - 'lib/suma/term_extractor.rb'
@@ -216,6 +223,7 @@ Metrics/ParameterLists:
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
+    - 'lib/suma/gcr_package.rb'
     - 'lib/suma/worker_pool.rb'
     - 'lib/suma/eengine/wrapper.rb'
     - 'lib/suma/jsdai/figure_image.rb'
@@ -259,6 +267,16 @@ RSpec/ContextWording:
 # Configuration parameters: Max, CountAsOne.
 RSpec/ExampleLength:
   Exclude:
+    - 'spec/suma/site_build_spec.rb'
+    - 'spec/suma/output_canonicalizer_spec.rb'
+    - 'spec/suma/anchor_validator_spec.rb'
+    - 'spec/suma/translation_ingester_spec.rb'
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
+    - 'spec/suma/schema_manifest_generator_spec.rb'
+    - 'spec/suma/schema_naming_spec.rb'
+    - 'spec/suma/cli/build_integration_spec.rb'
+    - 'spec/suma/artifact_server_spec.rb'
+    - 'spec/suma/gcr_package_spec.rb'
     - 'spec/suma/schema_cache_spec.rb'
     - 'spec/suma/worker_pool_spec.rb'
     - 'spec/suma/schema_collection_rebuild_targets_spec.rb'
@@ -338,6 +356,11 @@ RSpec/MessageSpies:
 # Configuration parameters: Max.
 RSpec/MultipleExpectations:
   Exclude:
+    - 'spec/suma/site_build_spec.rb'
+    - 'spec/suma/output_canonicalizer_spec.rb'
+    - 'spec/suma/cli/build_integration_spec.rb'
+    - 'spec/suma/artifact_server_spec.rb'
+    - 'spec/suma/gcr_package_spec.rb'
     - 'spec/suma/schema_cache_spec.rb'
     - 'spec/suma/worker_pool_spec.rb'
     - 'spec/suma/reproducibility_spec.rb'
@@ -400,11 +423,13 @@ RSpec/NestedGroups:
 RSpec/DescribeClass:
   Exclude:
     - 'spec/suma/reproducibility_spec.rb'
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
 
 RSpec/SpecFilePathFormat:
   Exclude:
     - '**/spec/routing/**/*'
     - 'spec/suma/cli/expressir_spec.rb'
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
 
 # Offense count: 1
 RSpec/StubbedMock:
@@ -415,6 +440,8 @@ RSpec/StubbedMock:
 # Configuration parameters: Max.
 RSpec/MultipleMemoizedHelpers:
   Exclude:
+    - 'spec/suma/ifc_profile_pipeline_spec.rb'
+    - 'spec/suma/gcr_package_spec.rb'
     - 'spec/suma/provenance_spec.rb'
     - 'spec/suma/worker_pool_spec.rb'
     - 'spec/suma/schema_cache_spec.rb'

data/CLAUDE.md

@@ -37,11 +37,15 @@ exe/suma reformat PATH                                  # Reformat EXP files (us
 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 ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE [-o OUT]  # Overlay translated localized-concept content onto extracted concepts
 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 package-gcr CONCEPTS_DIR --register register.yaml --shortname ID --version V --title T --description D -o OUT  # Package concepts into a .gcr archive
+exe/suma serve ARTIFACTS_DIR --port 2113  # Serve resolved URN artifacts with Accept negotiation
 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)
+exe/suma validate anchors SCHEMA_DOCS_PATH              # Rendered docs: every xref and in-page link resolves (exit 1 on dead links)
 ```
 
 ## Schema profiles
@@ -51,8 +55,10 @@ 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`.
+protocol), `generic` (no STEP conventions), and `ifc` (buildingSMART
+IFC editions: standalone classification, `IFC4`-style edition names via
+`/\Aifc\d+(x\d+)*\z/`). The CLI takes `--profile` on `export`,
+`extract-terms`, and `generate-register`.
 
 ## ISO 10303 AP publications
 
@@ -81,10 +87,12 @@ per-publication parent section.
 - **`SchemaCategory`** — value object mapping `ExpressSchema::Type` to a register/export category (id, label, prefix, types, directory). Single source of truth for category identity across `SchemaExporter`, `SchemaNaming`, and `RegisterManifestGenerator`
 - **`Urn`** — value object encapsulating ISO URN semantics (wildcard stripping, base/alias split, leaf composition for `for_schema`/`for_term`/`for_entity`)
 - **`TermExtractor`** — extracts EXPRESS entity concepts from a schema manifest into Glossarist v3 YAML format. Generates definitions with URN cross-references, processes remarks into notes, and resolves EXPRESS xrefs to URN mentions. Assigns stable UUIDv5 identifiers
+- **`TranslationIngester`** — T5 translation ingestion: overlays a YAML sequence of localized-concept entries (keyed by `concept_id` or localized UUID) onto extracted concepts through the Glossarist/lutaml-model framework. Entry fields win; omitted fields keep the source-language content; a new language is created with the same UUIDv5 convention as the linked localizations, and the persisted localization "id" is preserved (Glossarist parses it as `#id`, not `#uuid`)
 - **`RegisterManifestGenerator`** (file: `lib/suma/register_manifest_generator.rb`) — generates a Glossarist v3 `register.yaml` with hierarchical sections from a schema manifest. Classifies schemas via `ExpressSchema::Type` (DRY), delegates naming to `SchemaNaming` (OCP), orders resources before modules. Uses the Section model's `children` field for hierarchy
 - **`SchemaNaming`** — pure module that converts EXPRESS schema IDs to human-readable display names. Strips type suffixes (`_schema`/`_arm`/`_mim`/`_bom`), title-cases with acronym preservation (AIC, AEC, BREP, 2D, 3D…), lowercases function words, appends type labels (ARM/MIM)
-- **`SchemaTemplate::Plain` / `SchemaTemplate::Document`** — pure renderers for the AsciiDoc body fed to Metanorma (no I/O, no schema knowledge). `Document` adds cross-reference anchors and produces XML-only output
-- **`SchemaCompiler`** — orchestrates one schema's compilation: writes adoc + config, invokes `Metanorma::Compile`. Templates are injected via the constructor (composition over inheritance)
+- **`SchemaTemplate::Plain` / `SchemaTemplate::Document`** — pure renderers for the AsciiDoc body fed to Metanorma (no I/O, no schema knowledge). Both render the schema through `formatted_hyperlinked_adoc` (live cross-references) under the shared `Anchors` block, which emits one `[[id]]` per linkable element — schema-qualified ids plus bare `entity.attribute` pairs, matching Expressir's two xref forms. `Plain` produces HTML+XML for top-level schemas; `Document` produces XML-only for schemas-only entries. `validate anchors` verifies zero dead links in rendered docs
+- **`AnchorValidator`** — T4 dead-link gate: for every rendered `doc_*.adoc` + `doc_*.html`, each `<<target,...>>` xref must have an anchor in the HTML (unresolved xrefs are silently dropped by the renderer) and every in-page `href="#..."` must hit an id; cross-document xrefs are out of scope. `validate anchors SCHEMA_DOCS_PATH` exits 1 on violations
+- **`SchemaCompiler`** — orchestrates one schema's compilation: writes adoc + config, invokes `Metanorma::Compile`. Templates are injected via the constructor (composition over inheritance). A render key over adoc, config, schema source, and `Provenance.render_toolchain` is stored in `.suma-render-key` beside the outputs; an unchanged key with the requested outputs present reuses them without invoking Metanorma
 - **`SchemaCollection`** — orchestrates processing of all schemas from a config; selects `Plain` for top-level schemas and `Document` for schemas-only entries
 - **`SchemaExporter`** — standalone export of schemas from manifest or `.exp` files to a directory, with optional ZIP
 - **`CollectionManifest`** — pure data model (lutaml-model attributes + YAML mappings) for one node of a Metanorma collection manifest. No imperative methods
@@ -97,9 +105,13 @@ per-publication parent section.
 - **`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
+- **`SiteBuild`** — T3 site freshness: keys every source file under the site root (excluding generated trees, render copies, and the Relaton cache) plus the render toolchain, records the key and produced files in `_site/.suma-site-build.json`, and lets `Processor` skip the collection render when nothing changed. Generated per-document artifacts (`document*.xml*`, `*_index.html`, `*.err.html`, `*.log.txt`, temp files) are never treated as inputs
+- **`OutputCanonicalizer`** — T3 determinism: Metanorma assigns random UUIDs to manifest nodes without identifiers and stamps rendered documents with a random 8-letter root type. This pass rewrites those to position-derived UUIDv5s and a fixed marker in the emitted manifest and root XML, while preserving UUIDs that occur in source YAML, so identical builds are byte-identical
 - **`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`)
+- **`ArtifactServer`** — T2 development server for the resolved artifact tree (`serve DIRECTORY`): dependency-free TCP responder negotiating JSON vs HTML by the Accept header at URN-derived paths; production hosting maps the same paths statically
+- **`GcrPackage`** — T2 packaging (`package-gcr`): bundles extracted concepts into a GCR archive for the Glossarist Vocabulary Browser — `metadata.yaml` (identity, statistics, schema_version), `register.yaml`, and `concepts/` in the browser's canonical flat format (`termid`, `term`, `{lang}` blocks). Standard variant only; `created_at` is injectable for byte-reproducible archives
+- **`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 and reports unrecorded files under the recorded output roots (`_site`, `schema_docs`, `plain_schemas`); explicit exclusions cover build metadata such as the site state file and staged store. `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`). `Provenance.render_toolchain` keys rendered-document reuse
 - **`LinkValidator`** — validates EXPRESS cross-reference links against a `SchemaIndex`; returns `LinkValidationResult` structs for unresolved links
 
 ### CLI structure

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,19 @@ $ 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 ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE [-o OUT]    # Overlay translated content onto extracted concepts
+  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 package-gcr CONCEPTS_DIR --register=REGISTER -o OUTPUT         # Package concepts into a .gcr archive
+  suma serve DIRECTORY                                                # Serve resolved artifacts (Accept negotiation)
   suma validate SUBCOMMAND ...ARGS                                    # Validate express documents
 ----
 
@@ -65,10 +77,31 @@ 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`.
 
+Repeated builds reuse work and are reproducible: a schema document is rendered
+again only when its adoc, schema config, schema source, or the rendering
+toolchain changed, and the collection render is skipped entirely when no site
+input changed (state: `_site/.suma-site-build.json`). Metanorma's random
+manifest identifiers and per-document type markers are canonicalized, so two
+identical builds produce byte-identical output. A provenance manifest covers
+`schema_docs`, `plain_schemas`, and `_site`, and verification reports files
+that appeared under those roots without being recorded (build metadata such as
+the site state file is excluded explicitly).
+
+Top-level schema documents render with live cross-reference links: every
+`schema.entity` and `entity.attribute` reference Expressir emits becomes an
+in-page link, and `suma validate anchors` verifies that no link is dead.
+
 [example]
 ====
 .To compile SRL subset test collection
@@ -141,6 +174,7 @@ $ suma validate SUBCOMMAND [options]
 Subcommands:
 
 `links`:: Validate EXPRESS links
+`closure`:: Validate referential closure over the whole corpus
 
 ==== Links subcommand
 
@@ -176,6 +210,36 @@ 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.
+
+==== Anchors subcommand
+
+The `anchors` subcommand checks rendered schema documents for dead links:
+every Expressir cross-reference (`<<schema.entity,...>>`,
+`<<entity.attribute,...>>`) emitted in a compiled `doc_*.adoc` must have a
+matching anchor in its rendered `doc_*.html`, and every in-page `href` must
+point at an existing id. It exits non-zero on violations.
+
+[source,sh]
+----
+$ suma validate anchors SCHEMA_DOCS_PATH
+----
+
 
 === Generate schemas command
 
@@ -225,7 +289,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 +303,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 +341,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
@@ -301,6 +367,37 @@ $ bundle exec suma extract-terms schemas-activity-modules.yml terms_output
 ----
 ====
 
+=== Ingest translations command
+
+The `suma ingest-translations` command overlays translated content onto
+extracted concepts. A translations file is a YAML sequence of
+localized-concept documents, each keyed by concept id (or localized
+UUID) and carrying the fields to apply:
+
+[source,yaml]
+----
+- concept_id: example_schema.part
+  data:
+    language_code: fra
+    terms:
+      - designation: pièce
+        type: expression
+        normative_status: preferred
+    definition:
+      - content: "Composant d'un assemblage."
+----
+
+Every field the entry provides replaces that localization's field; every
+field it omits keeps the source-language content (a language absent from
+the extracted concepts is created with the same stable UUID convention
+the linked localizations use). Updated concepts are written in place, or
+to `--output` when given.
+
+[source,sh]
+----
+$ suma ingest-translations CONCEPTS_DIR TRANSLATIONS_FILE [-o OUTPUT_DIR]
+----
+
 
 === Generate register command
 
@@ -326,6 +423,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 +625,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 +748,105 @@ 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)
+`ifc`:: buildingSMART IFC editions: one standalone schema per edition (`ifc4`, `ifc4x3`, ...), edition names preserved uppercase (`IFC4`, `IFC4X3`), Ifc-prefixed declarations, one `Other Schemas` register category
+
+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
+----
+
+=== Package concepts for the Vocabulary Browser
+
+The `package-gcr` command bundles extracted concepts into a GCR
+(Glossarist Concept Repository) archive — the sealed distribution format
+consumed by the Glossarist Vocabulary Browser:
+
+[source,sh]
+----
+$ suma package-gcr CONCEPTS_DIR --register register.yaml \
+    --shortname my-dataset --version 1.0.0 \
+    --title "My Dataset" --description "Concepts from my corpus" \
+    -o OUT
+----
+
+The archive contains `metadata.yaml` (identity, statistics), the original
+`register.yaml`, and `concepts/` in the browser's canonical flat format
+(`termid`, `term`, one block per language). Both a versioned
+(`{shortname}-{version}.gcr`) and an unversioned (`{shortname}.gcr`)
+archive are written. Pass `--created-at` to pin the package timestamp for
+byte-reproducible archives. Point the browser's `datasets.yml` at the
+published archive (or at the concepts directory in development via
+`localPath`).
+
+=== Serve resolved artifacts
+
+`suma serve` serves a `resolve --all` artifact tree at its URN-derived
+paths, returning JSON or HTML according to the request's `Accept`
+header:
+
+[source,sh]
+----
+$ suma serve OUT --port 2113
+$ curl -H "Accept: application/json" \
+    http://localhost:2113/urn/iso/std/iso/10303/-2/ed-2/en/tech/action_schema.action
+----
+
+Production hosting maps the same paths statically; no application server
+is required.
+
+=== 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 +875,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 +1375,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/lib/suma/anchor_validator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Suma
+  # Validates that every cross-reference a rendered schema document emits
+  # resolves inside it. The Expressir hyperlinked source emits xref macros
+  # (`<<schema.entity,...>>`, `<<entity.attribute,...>>`); when a target is
+  # missing, the renderer silently drops the link, so the check is done on
+  # the source macros against the anchors present in the rendered HTML —
+  # plus the reverse check that every in-page href hits an existing id.
+  class AnchorValidator
+    XREF_PATTERN = /<<([^,>]+)(?:,[^>]*)?>>/
+    ID_PATTERN = /id="([^"]+)"/
+    FRAGMENT_PATTERN = /href="#([^"]+)"/
+
+    # @param directory [String] tree of compiled schema docs (doc_*.adoc
+    #   with their rendered doc_*.html)
+    def initialize(directory)
+      @directory = directory
+    end
+
+    # @return [Array<LinkValidationResult>] dead links (empty = valid)
+    def validate
+      Dir.glob(File.join(@directory, "**", "doc_*.adoc"))
+        .flat_map { |adoc| validate_document(adoc) }
+    end
+
+    private
+
+    def validate_document(adoc)
+      html = adoc.sub(/\.adoc\z/, ".html")
+      return [missing_html(adoc, html)] unless File.file?(html)
+
+      content = File.read(adoc)
+      ids, fragments = rendered_digests(html)
+
+      xref_violations(adoc, content, ids, fragments) +
+        fragment_violations(html, ids)
+    end
+
+    def rendered_digests(html)
+      rendered = File.read(html)
+      [rendered.scan(ID_PATTERN).flatten.uniq,
+       rendered.scan(FRAGMENT_PATTERN).flatten.uniq]
+    end
+
+    def xref_violations(adoc, content, ids, fragments)
+      content.scan(XREF_PATTERN).flatten.uniq.filter_map do |target|
+        next if cross_document?(target) || resolved?(target, ids, fragments)
+
+        LinkValidationResult.new(
+          file: adoc, line: nil, link: target,
+          reason: "cross-reference has no anchor in the rendered document"
+        )
+      end
+    end
+
+    def fragment_violations(html, ids)
+      File.read(html).scan(FRAGMENT_PATTERN).flatten.uniq.filter_map do |frag|
+        next if ids.include?(frag)
+
+        LinkValidationResult.new(
+          file: html, line: nil, link: "##{frag}",
+          reason: "in-page link points at no anchor in the document"
+        )
+      end
+    end
+
+    # Xrefs that cross documents (Asciidoctor `path.adoc#anchor` syntax)
+    # resolve against other pages and are out of scope here.
+    def cross_document?(target)
+      target.include?("/") || target.include?("#")
+    end
+
+    def resolved?(target, ids, fragments)
+      ids.include?(target) || fragments.include?(target)
+    end
+
+    def missing_html(adoc, html)
+      LinkValidationResult.new(
+        file: adoc, line: nil, link: html,
+        reason: "no rendered HTML next to the adoc source"
+      )
+    end
+  end
+end