Add cross-converter interoperability harness

.github/workflows/interop-matrix-ci.yml

@@ -0,0 +1,95 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file to you under the
+# Apache License, Version 2.0 (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+name: Cross-converter Interop Matrix
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'interop/**'
+      - 'converters/**'
+      - 'examples/**'
+      - 'core-spec/**'
+      - 'python/**'
+      - 'validation/**'
+      - '.github/workflows/interop-matrix-ci.yml'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'interop/**'
+      - 'converters/**'
+      - 'examples/**'
+      - 'core-spec/**'
+      - 'python/**'
+      - 'validation/**'
+      - '.github/workflows/interop-matrix-ci.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@03ad4de0992f5dab5e18fcb136590ce7c4a0ac95 # v5.6.0
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'maven'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
+
+      - name: Lint interop harness
+        working-directory: interop
+        run: |
+          uv sync --frozen
+          uv run ruff check runner.py adapters tests
+
+      - name: Test interop harness
+        working-directory: interop
+        run: |
+          uv sync --frozen
+          uv run pytest
+
+      - name: Generate report-only interoperability matrix
+        run: |
+          uv run --project interop python interop/runner.py \
+            --report interop-report.md \
+            --report-only
+          cat interop-report.md >> "${GITHUB_STEP_SUMMARY}"
+
+      - name: Upload interoperability report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: cross-converter-interop-report
+          path: interop-report.md
+          if-no-files-found: error

interop/README.md

@@ -0,0 +1,48 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements. See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership. The ASF licenses this file to you under the
+  Apache License, Version 2.0 (the "License"); you may not use this file except
+  in compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+# Cross-converter interoperability
+
+The `interop` harness tests the hub-and-spoke contract across converter boundaries rather than only testing each converter's own round trip.
+
+## Tiers
+
+**Tier A** sends the canonical Ossie example through every declared export capability. A successful process is not sufficient: the manifest also declares a converter-specific non-empty assertion, so a loadable vendor document with no meaningful members is graded `EMPTY` rather than `OK`.
+
+**Tier B** starts from each declared native fixture and evaluates `source native -> Ossie -> target native -> Ossie`. The final Ossie document is validated with `validation/validate.py`. A target must declare both export and import capabilities to participate.
+
+The report grades cells as `OK`, `LOSSY`, `EMPTY`, `FAIL`, or `SKIP`. Warning counts are retained so report-only CI can expose known loss before individual cells are promoted to blocking gates. Build/setup warnings are deliberately excluded from semantic loss grading.
+
+**Tier C** is available for converters that expose an independent native compiler or validator. A manifest `native_gate` can be unconditional or guarded by an environment variable; the tier is emitted when at least one selected converter declares a gate.
+
+## Manifest
+
+`manifest.yaml` is the compatibility boundary between the harness and converter-specific command lines. Each converter directory must have an entry, even when it is currently skipped. Executable capabilities declare their command, output shape, and non-empty assertion.
+
+This keeps CLI differences out of the runner and makes unsupported toolchains explicit. GoodData is wired through a thin Python API adapter. The ontology converter participates asymmetrically through its real Palantir import boundary: a committed minimal Palantir export feeds Tier B as a source, while Tier A and ontology-as-target cells remain `SKIP` because no Ossie-to-Palantir exporter exists. Salesforce runs through its shaded executable JAR. Polaris runs its public CLI against an in-process Iceberg REST catalog, which exercises the real HTTP boundary without requiring an external service. Wisdom is installed transiently with `uv --with`, so its missing converter-local lockfile does not mutate the checkout. The legacy `converters/gsf` compatibility directory is the only intentional hard skip; the executable NVIDIA GSF converter is represented by `nvidia`.
+
+## Running
+
+```bash
+cd interop
+uv sync --frozen
+uv run pytest
+cd ..
+uv run --project interop python interop/runner.py --report interop-report.md --report-only
+```
+
+Use `--include databricks,nvidia` for a focused run, `--tier a`, `--tier b`, or `--tier c` to select one tier, and omit `--report-only` when failures should produce a non-zero exit code. Tier C internally materializes the Tier B target output before invoking native gates.

interop/adapters/gooddata.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file to you under the
+# Apache License, Version 2.0 (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""CLI shim exposing GoodData's Python API to the interop harness."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import yaml
+from ossie_gooddata import gooddata_to_ossie, ossie_to_gooddata
+from ossie_gooddata.models import gd_model_from_dict, gd_model_to_dict
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("direction", choices=("export", "import"))
+    parser.add_argument("--input", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+
+    if args.direction == "export":
+        ossie = yaml.safe_load(args.input.read_text(encoding="utf-8"))
+        native = gd_model_to_dict(ossie_to_gooddata(ossie))
+        args.output.write_text(json.dumps(native, indent=2) + "\n", encoding="utf-8")
+        return 0
+
+    native = json.loads(args.input.read_text(encoding="utf-8"))
+    ossie = gooddata_to_ossie(gd_model_from_dict(native))
+    args.output.write_text(yaml.safe_dump(ossie, sort_keys=False), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

interop/adapters/java_build.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file to you under the
+# Apache License, Version 2.0 (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Build a Java converter in an isolated interop workspace."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+SUPPORTED = {"polaris", "salesforce"}
+
+
+def _copy_module(module: str, output: Path) -> Path:
+    sandbox = output / "repo"
+    module_source = REPO / "converters" / module
+    module_target = sandbox / "converters" / module
+    shutil.copytree(
+        module_source,
+        module_target,
+        ignore=shutil.ignore_patterns("target", ".idea", "*.iml"),
+    )
+    if module == "salesforce":
+        shutil.copytree(REPO / "core-spec", sandbox / "core-spec")
+    return module_target
+
+
+def build(module: str, output: Path) -> None:
+    if module not in SUPPORTED:
+        raise ValueError(f"unsupported Java converter: {module}")
+    if output.exists():
+        shutil.rmtree(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    module_root = _copy_module(module, output)
+
+    command = ["mvn", "-q", "-DskipTests", "package"]
+    if module == "polaris":
+        command.extend(
+            [
+                "dependency:build-classpath",
+                "-Dmdep.outputFile=target/interop-classpath.txt",
+            ]
+        )
+    process = subprocess.run(
+        command,
+        cwd=module_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if process.stdout:
+        print(process.stdout, end="")
+    if process.stderr:
+        print(process.stderr, end="", file=__import__("sys").stderr)
+    if process.returncode != 0:
+        raise SystemExit(process.returncode)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--module", required=True, choices=sorted(SUPPORTED))
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+    build(args.module, args.output)
+
+
+if __name__ == "__main__":
+    main()

interop/adapters/ontology.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file to you under the
+# Apache License, Version 2.0 (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Interop adapter for the ontology converter's Palantir import boundary."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO / "converters" / "ontology" / "src"))
+
+from ossie_ontology.converter.ossie_to_spec.converter import (
+    OssieToSpecConverter,
+)
+from ossie_ontology.converter.palantir_to_ossie.converter import (
+    PalantirToOssieConverter,
+)
+from ossie_ontology.external.palantir.parser import PalantirParser
+
+
+def import_palantir(input_path: Path, output_path: Path) -> None:
+    palantir = PalantirParser().parse(input_path)
+    ontology = PalantirToOssieConverter().convert(palantir, "PALANTIR", "PALANTIR")
+    spec = OssieToSpecConverter.convert(ontology)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(spec.dump_yaml(), encoding="utf-8")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("mode", choices=("import",))
+    parser.add_argument("--input", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+    import_palantir(args.input, args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())