suma 0.5.7 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98f57b1e48077074a8b282922f6b1196a718fc50bfae43d31fe81dad940d0092
-  data.tar.gz: 3c0982d9e700c84b6cfc9030d835cef3f2bd34ae3309df3ce622f25301124a11
+  metadata.gz: 3674c1699305e230eabb86ed343195cd0b6915c063b77b3b1fb540ce03a6e684
+  data.tar.gz: 8f86f1e113c3774de773261c96cab1292222be7e5ae97e9b463a2136c40aefce
 SHA512:
-  metadata.gz: 95856f79045ee2124742c28d86c18fe50401bbc642ad44872912b0e05e31713a9fb479601a18f0320810583f2a2ae1b5de2d5d897815668d56087f6078af7d90
-  data.tar.gz: d0514ee213feaed81c9f4d79ff10728634c60ba5c731cc9a2dc9adae64fa87d45ec7512c6697eb31c5de9efc9f75198449d90631d1a032c69e65833b3aee7bc3
+  metadata.gz: 60c730b7f8dc973837b72f6651877a74da259c5e887ee4429d9f884fd318192223dacd2a4be7b7631b9863b42c987fe642649cc89166f67ba343e33b78510db1
+  data.tar.gz: 6ad73db79afdc62625d6a11ce94a3759cbfdbeb74151fb6c8f89c9ca0105f372ead7f95fa36afd010a9244979612e9693712ed7a35c12789f6f64b8881aff692

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,38 @@
+name: release-provenance
+
+on:
+  release:
+    types: [published]
+  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/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

data/bin/benchmark_corpus

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Nightly scale benchmark: generates a synthetic EXPRESS corpus, then times
+# the corpus-scale operations (parse/graph, closure, OWL projection) and
+# asserts wall-time and peak-RSS budgets. Budgets are environment-tunable so
+# CI machines can be calibrated without code changes.
+
+require "suma"
+require "tmpdir"
+require "fileutils"
+require "json"
+
+module CorpusBenchmark
+  SCHEMA_COUNT = Integer(ENV.fetch("SUMA_BENCH_SCHEMAS", "1000"))
+  MAX_SECONDS = Float(ENV.fetch("SUMA_BENCH_MAX_SECONDS", "180"))
+  MAX_RSS_MB = Integer(ENV.fetch("SUMA_BENCH_MAX_RSS_MB", "2048"))
+  URN = "urn:example:benchmark:corpus:ed-1:en"
+
+  module_function
+
+  # Half resources, half modules; each module USEs one resource so the graph
+  # has interface edges (dependents are exercised by the closure walk).
+  def generate(directory)
+    resources = SCHEMA_COUNT / 2
+    FileUtils.mkdir_p(File.join(directory, "resources"))
+    FileUtils.mkdir_p(File.join(directory, "modules"))
+    manifest = { "schemas" => {} }
+
+    resources.times do |index|
+      id = format("res_%04d", index)
+      write_schema(directory, "resources", id, resource_source(id, index))
+      manifest["schemas"][id] = { "path" => "resources/#{id}.exp" }
+    end
+
+    (SCHEMA_COUNT - resources).times do |index|
+      id = format("mod_%04d", index)
+      resource = format("res_%04d", index)
+      write_schema(directory, "modules", id,
+                   module_source(id, index, resource))
+      manifest["schemas"][id] = { "path" => "modules/#{id}.exp" }
+    end
+
+    path = File.join(directory, "schemas.yaml")
+    File.write(path, YAML.dump(manifest))
+    path
+  end
+
+  def resource_source(id, index)
+    <<~EXPRESS
+      SCHEMA #{id};
+      ENTITY thing_#{format('%04d', index)};
+        name : STRING;
+        weight : REAL;
+      END_ENTITY;
+      END_SCHEMA;
+    EXPRESS
+  end
+
+  def module_source(id, index, resource)
+    <<~EXPRESS
+      SCHEMA #{id};
+      USE FROM #{resource};
+      ENTITY wrapper_#{format('%04d', index)};
+        item : thing_#{format('%04d', index)};
+      END_ENTITY;
+      END_SCHEMA;
+    EXPRESS
+  end
+
+  def write_schema(directory, kind, id, source)
+    File.write(File.join(directory, kind, "#{id}.exp"), source)
+  end
+
+  def measure
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    value = yield
+    [value, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
+  end
+
+  def peak_rss_mb
+    if File.exist?("/proc/self/status")
+      File.read("/proc/self/status")[/VmHWM:\s+(\d+)/, 1].to_i / 1024.0
+    else
+      `ps -o rss= -p #{Process.pid}`.to_i / 1024.0
+    end.round
+  end
+
+  def run
+    Dir.mktmpdir("suma-benchmark") do |directory|
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      manifest = generate(directory)
+
+      graph, graph_seconds = measure { Suma::CorpusGraph.from_manifest(manifest) }
+      violations, closure_seconds = measure do
+        Suma::ClosureValidator.new(graph).validate_manifest(manifest)
+      end
+      projection, owl_seconds = measure do
+        Suma::OwlProjection.new(manifest, urn: URN)
+      end
+      turtle, turtle_seconds = measure { projection.to_turtle }
+      total = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      rss = peak_rss_mb
+
+      report = {
+        schemas: SCHEMA_COUNT,
+        graph_seconds: graph_seconds.round(2),
+        closure_seconds: closure_seconds.round(2),
+        owl_seconds: owl_seconds.round(2),
+        turtle_seconds: turtle_seconds.round(2),
+        total_seconds: total.round(2),
+        peak_rss_mb: rss,
+        closure_violations: violations.length,
+        turtle_bytes: turtle.bytesize,
+        budgets: { max_seconds: MAX_SECONDS, max_rss_mb: MAX_RSS_MB },
+      }
+      puts JSON.pretty_generate(report)
+
+      failures = []
+      unless violations.empty?
+        failures << "#{violations.length} closure violations"
+      end
+      if total > MAX_SECONDS
+        failures << "wall time #{total.round(2)}s > #{MAX_SECONDS}s"
+      end
+      if rss > MAX_RSS_MB
+        failures << "peak RSS #{rss}MB > #{MAX_RSS_MB}MB"
+      end
+      unless failures.empty?
+        warn "benchmark FAILED: #{failures.join('; ')}"
+        exit 1
+      end
+      puts "benchmark passed"
+    end
+  end
+end
+
+CorpusBenchmark.run if $PROGRAM_NAME == __FILE__

data/bin/release_provenance

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Emit provenance for a release build: the built gem's sha256 plus the
+# dependency lockfile and toolchain versions. Run after `gem build`.
+
+require "suma"
+
+ROOT = File.expand_path("..", __dir__)
+gem_file = Dir[File.join(ROOT, "*.gem")].max
+abort "release_provenance: no built gem found in #{ROOT}" unless gem_file
+
+manifest_path = File.join(Dir.pwd, "provenance.json")
+Suma::Provenance.write(
+  manifest_path,
+  inputs: [
+    File.join(ROOT, "Gemfile.lock"),
+    File.join(ROOT, "suma.gemspec"),
+  ],
+  outputs: [gem_file],
+)
+
+problems = Suma::Provenance.verify(manifest_path)
+unless problems.empty?
+  warn "release_provenance: verification failed: #{problems.join('; ')}"
+  exit 1
+end
+
+puts "Wrote #{manifest_path} (#{File.basename(gem_file)})"
+
+sign_method = ENV.fetch("SUMA_PROVENANCE_SIGN", nil)
+sign_method = nil if sign_method.to_s.empty?
+if sign_method
+  sign_key = ENV.fetch("SUMA_PROVENANCE_SIGN_KEY", nil)
+  sign_key = nil if sign_key.to_s.empty?
+  signature = Suma::Provenance.sign(
+    manifest_path, method: sign_method, key: sign_key
+  )
+  puts "Signed provenance (#{sign_method}): #{signature}"
+end

data/lib/suma/build_plan.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "fileutils"
+
+module Suma
+  # Decides which schemas an incremental build must re-render.
+  #
+  # The state is a map of schema id → sha256 of its source. A schema is
+  # changed when its digest differs from the previous build; rendering is
+  # required for every changed schema plus all transitive dependents, because
+  # a dependent's cross-references and rendered anchors may shift. The
+  # dependents come from the corpus graph (S1), the same USE/REFERENCE edges
+  # that drive change impact (S3).
+  class BuildPlan
+    # @param entries [Array<#id,#path>] schema manifest entries
+    # @param graph [CorpusGraph]
+    # @param previous_state [Hash{String=>String}] digest per schema id
+    def initialize(entries:, graph:, previous_state: {})
+      @entries = entries
+      @graph = graph
+      @previous_state = previous_state || {}
+      @ids_by_key = entries.to_h { |entry| [entry.id.downcase, entry.id] }
+    end
+
+    # @return [Array<String>] declared ids whose source differs since the
+    #   previous build (all ids on a first build)
+    def changed
+      current_state.reject do |id, digest|
+        @previous_state[id] == digest
+      end.keys
+    end
+
+    # @return [Array<String>] schemas to re-render: every changed schema plus
+    #   its transitive dependents; empty when nothing changed
+    def rebuild
+      changed_ids = changed
+      return [] if changed_ids.empty?
+
+      expanded = changed_ids.flat_map do |id|
+        [id] + @graph.dependents_of(id).map { |key| @ids_by_key[key] || key }
+      end
+      expanded.uniq
+    end
+
+    # @return [Hash{String=>String}] digest per schema id
+    def current_state
+      @current_state ||= @entries.to_h do |entry|
+        [entry.id, Digest::SHA256.file(entry.path.to_s).hexdigest]
+      end
+    end
+
+    # Persist the current state for the next incremental build.
+    def self.write_state(path, state)
+      FileUtils.mkdir_p(File.dirname(path))
+      temp = "#{path}.#{Process.pid}.tmp"
+      File.write(temp, JSON.pretty_generate(state))
+      File.rename(temp, path)
+    ensure
+      File.delete(temp) if temp && File.exist?(temp)
+    end
+
+    # @return [Hash{String=>String}] the previous state, empty when absent
+    def self.read_state(path)
+      return {} unless path && File.exist?(path)
+
+      JSON.parse(File.read(path))
+    end
+  end
+end