Support both oci-dir and oci-archive formats for OMMX Local Registry storage

ARTIFACT.md

@@ -51,3 +51,71 @@ OMMX Artifact is a collection of `config`, `layers`, and annotations.
 
 Note that other annotations listed above are also allowed.
 The key may not start with `org.ommx.v1.`, but must be a valid reverse domain name as specified by OCI specification.
+
+Storage Formats
+---------------
+
+OMMX Local Registry supports two storage formats for artifacts:
+
+### OCI Directory Format (oci-dir)
+
+The traditional format where artifacts are stored as directory structures following the OCI Image Layout specification. Each artifact is stored as a directory containing:
+- `oci-layout` file indicating OCI compliance
+- `blobs/` directory containing content-addressable blobs
+- `index.json` file with manifest references
+
+This format is suitable for:
+- Local development and testing
+- File system-based storage
+- Cases where individual blobs need direct access
+
+### OCI Archive Format (oci-archive)
+
+A single-file format where the entire artifact is packaged as a tar archive with `.ommx` extension. This format contains the same OCI structure but packaged for easier distribution.
+
+This format is suitable for:
+- Cloud object storage systems (AWS S3, Google Cloud Storage, etc.)
+- Artifact distribution and sharing
+- Backup and archiving scenarios
+- Network transfer optimization
+
+### Format Selection and Compatibility
+
+- **New artifacts default to oci-archive format** for better cloud storage compatibility
+- **Both formats are fully supported** for loading and manipulation
+- **Backward compatibility is maintained** - existing oci-dir artifacts continue to work
+- **Format detection is automatic** - the system transparently handles both formats
+- **Cross-format operations are supported** - you can load from one format and save to another
+
+### Local Registry Directory Structure
+
+Artifacts are stored in the local registry with the following path structure. Image names are converted to file system paths with `:` (colon) in tags escaped to `__` (double underscore):
+
+**Example: `ghcr.io/jij-inc/ommx/qplib:3734`**
+
+```
+<LOCAL_REGISTRY_ROOT>/
+└── ghcr.io/
+    └── jij-inc/
+        └── ommx/
+            └── qplib/
+                ├── __3734/              # oci-dir format (: converted to __)
+                │   ├── oci-layout
+                │   ├── index.json
+                │   └── blobs/
+                │       └── sha256/...
+                │
+                └── __3734.ommx         # oci-archive format (: converted to __)
+```
+
+**Path Conversion Rules:**
+- Tags with `:` are escaped to `__` (e.g., `my-app:v1.0` → `my-app/__v1.0`)
+- oci-dir format: `<escaped-path>/`
+- oci-archive format: `<escaped-path>.ommx`
+
+**Format Priority:**
+When both formats exist for the same image name, **oci-archive format takes precedence**. The system checks for the `.ommx` file first, then falls back to the directory format.
+
+### Migration Between Formats
+
+The OMMX artifact system provides transparent format conversion. Artifacts can be loaded from either format and saved to either format without manual intervention. The system automatically detects the source format based on file system structure (directory vs. archive file) and handles the conversion internally.

CLAUDE.md

@@ -43,6 +43,61 @@ The project has completed its migration from Protocol Buffers auto-generated Pyt
 
 **Implementation Details**: See actual code in `rust/ommx/src/` for current type definitions and API.
 
+### Artifact API (Unified Format Handling) ✅
+
+The project uses a unified `Artifact` enum API that handles both oci-dir and oci-archive formats transparently.
+
+**Rust API:**
+```rust
+use ommx::artifact::{Artifact, Builder};
+
+// Load from either format (automatic detection)
+let mut artifact = Artifact::from_oci_archive(path)?;
+let mut artifact = Artifact::from_oci_dir(path)?;
+let mut artifact = Artifact::from_remote(image_name)?;
+let artifact = Artifact::load(&image_name)?;  // Auto-detect local or pull from remote
+
+// Save to specific format
+artifact.save()?;  // Default: oci-archive to local registry
+artifact.save_as_archive(path)?;
+artifact.save_as_dir(path)?;
+
+// Pull from remote
+artifact.pull()?;  // Saves as oci-archive to local registry
+
+// Build new artifacts
+let mut builder = Builder::new_archive(path, image_name)?;
+let mut builder = Builder::for_github("org", "repo", "name", "tag")?;
+builder.add_instance(instance, annotations)?;
+builder.add_annotation("key".to_string(), "value".to_string());
+let artifact = builder.build()?;
+```
+
+**Python API:**
+```python
+from ommx.artifact import Artifact, ArtifactBuilder
+
+# Load from either format (automatic detection)
+artifact = Artifact.load("image-name:tag")
+artifact = Artifact.load_archive("path.ommx")
+artifact = Artifact.load_dir("path/to/dir")
+
+# Build new artifacts (defaults to oci-archive)
+builder = ArtifactBuilder.new("image-name:tag")
+builder.add_instance(instance)
+builder.add_annotation("key", "value")
+artifact = builder.build()
+
+# For legacy oci-dir format
+builder = ArtifactBuilder.new_dir(path, "image-name:tag")
+```
+
+**Key Points:**
+- The API automatically detects and handles both oci-dir and oci-archive formats
+- New artifacts default to oci-archive format for better cloud storage compatibility
+- Format conversion happens transparently during load/save operations
+- Python API maintains backward compatibility - no changes needed in user code
+
 ## Development Commands
 
 This project uses [Taskfile](https://taskfile.dev/) for task management. **⚠️ All commands must be run from the project root directory.**

python/ommx-tests/tests/conftest.py

@@ -0,0 +1,30 @@
+"""
+Global pytest configuration for ommx-tests.
+
+This module sets up fixtures that are shared across all test modules.
+"""
+
+import tempfile
+import shutil
+from pathlib import Path
+
+import pytest
+
+from ommx.artifact import set_local_registry_root
+
+
+@pytest.fixture(scope="session", autouse=True)
+def setup_local_registry():
+    """
+    Set up a temporary local registry for all tests.
+
+    This fixture is automatically used for all tests (autouse=True) and runs once
+    per test session (scope="session"). The local registry root can only be set
+    once per process due to OnceLock constraints in the Rust implementation.
+    """
+    temp_dir = tempfile.mkdtemp(prefix="ommx-test-registry-")
+    try:
+        set_local_registry_root(temp_dir)
+        yield Path(temp_dir)
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)

python/ommx-tests/tests/test_artifact_dual_format.py

@@ -0,0 +1,105 @@
+"""
+Test dual format support for OMMX artifacts (oci-dir and oci-archive).
+
+This test validates that:
+1. New artifacts default to oci-archive format
+2. Both oci-dir and oci-archive formats can be loaded
+3. Backward compatibility is maintained
+4. get_artifact_path correctly identifies both formats
+"""
+
+import uuid
+
+import pytest
+
+from ommx.artifact import (
+    Artifact,
+    ArtifactBuilder,
+    get_local_registry_path,
+)
+from ommx.testing import SingleFeasibleLPGenerator, DataType
+
+
+@pytest.fixture
+def test_instance():
+    """Create a test instance for artifact tests."""
+    generator = SingleFeasibleLPGenerator(3, DataType.INT)
+    return generator.get_v1_instance()
+
+
+def test_new_artifacts_default_to_archive_format(test_instance):
+    """Test that new artifacts created with ArtifactBuilder.new() use oci-archive format."""
+    image_name = f"test.local/archive-default:{uuid.uuid4()}"
+
+    # Build artifact using the default new() method
+    builder = ArtifactBuilder.new(image_name)
+    builder.add_instance(test_instance)
+    artifact = builder.build()
+
+    # Verify artifact is stored as oci-archive format (.ommx file)
+    base_path = get_local_registry_path(image_name)
+    archive_path = base_path.with_suffix(".ommx")
+    assert archive_path.exists()
+    assert archive_path.is_file()
+    assert archive_path.suffix == ".ommx"
+
+    # Verify we can load it back
+    loaded = Artifact.load(image_name)
+    assert loaded.image_name == image_name
+    assert len(loaded.layers) == len(artifact.layers)
+
+
+def test_legacy_oci_dir_format_still_works(test_instance):
+    """Test that the legacy oci-dir format can still be created and loaded."""
+    image_name = f"test.local/dir-legacy:{uuid.uuid4()}"
+
+    # Build artifact using the dir format via new_dir()
+    dir_path = get_local_registry_path(image_name)
+    builder = ArtifactBuilder.new_dir(dir_path, image_name)
+    builder.add_instance(test_instance)
+    artifact = builder.build()
+
+    # Verify artifact is stored as oci-dir format (directory)
+    assert dir_path.exists()
+    assert dir_path.is_dir()
+    assert (dir_path / "oci-layout").exists()
+
+    # Verify we can load it back
+    loaded = Artifact.load(image_name)
+    assert loaded.image_name == image_name
+    assert len(loaded.layers) == len(artifact.layers)
+
+
+def test_dual_format_interoperability(test_instance):
+    """Test that both formats work seamlessly together."""
+    archive_image = f"test.local/interop-archive:{uuid.uuid4()}"
+    dir_image = f"test.local/interop-dir:{uuid.uuid4()}"
+
+    # Create artifacts in both formats
+    archive_builder = ArtifactBuilder.new(archive_image)
+    archive_builder.add_instance(test_instance)
+    archive_builder.build()
+
+    dir_path = get_local_registry_path(dir_image)
+    dir_builder = ArtifactBuilder.new_dir(dir_path, dir_image)
+    dir_builder.add_instance(test_instance)
+    dir_builder.build()
+
+    # Both can be loaded with the same API
+    loaded_archive = Artifact.load(archive_image)
+    loaded_dir = Artifact.load(dir_image)
+    assert loaded_archive.image_name == archive_image
+    assert loaded_dir.image_name == dir_image
+
+    # get_local_registry_path returns base path, format checked via path suffix/directory
+    archive_base_path = get_local_registry_path(archive_image)
+    archive_file = archive_base_path.with_suffix(".ommx")
+    assert archive_file.exists() and archive_file.is_file()
+
+    dir_base_path = get_local_registry_path(dir_image)
+    assert dir_base_path.exists() and dir_base_path.is_dir()
+
+    # Non-existent artifacts don't have files/directories
+    nonexistent_base = get_local_registry_path(f"test.local/nonexistent:{uuid.uuid4()}")
+    assert not nonexistent_base.exists()
+    assert not nonexistent_base.with_suffix(".ommx").exists()