just-dna-format 0.1.0__tar.gz

just_dna_format-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.3
+Name: just-dna-format
+Version: 0.1.0
+Summary: Declarative schema + integrity contract for just-dna annotation modules (DSL spec, manifest, digests)
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# just-dna-module
+
+The declarative **manifest contract** and **integrity primitives** for just-dna annotation
+modules. Dependency-light (Pydantic + stdlib only) so it can be shared as the single source of
+truth by both:
+
+- **`just-dna-pipelines`** — *emits* `manifest.json` when it compiles a module, and
+- **`just-dna-marketplace`** — *indexes, serves, and verifies* those manifests.
+
+Keeping the contract in one small package prevents the two sides from drifting.
+
+## What's here
+
+| Module | Contents |
+|---|---|
+| `just_dna_format.manifest` | `ModuleManifest` + sub-models (`Identity`, `Display`, `Stats`, `Compilation`, `FileEntry`, `Artifact`); `read_manifest` / `write_manifest`. Mirrors the marketplace SPEC §4. |
+| `just_dna_format.integrity` | `sha256_file`, `artifact_digest` (canonical Merkle root), `build_artifact`, `verify_manifest` (verify-then-install), `IntegrityError`. SPEC §5. |
+| `just_dna_format.identity` | Name/namespace rules, `canonical_id`, SemVer `Version` + `parse_version`, `version_from_legacy` (`vN → N.0.0`), `latest`. SPEC §6. |
+
+## Usage
+
+```python
+from just_dna_format.manifest import ModuleManifest, read_manifest
+from just_dna_format.integrity import build_artifact, verify_manifest
+
+# Compiler side: hash outputs and record the digest.
+artifact = build_artifact(output_dir, ["weights.parquet", "annotations.parquet", "studies.parquet"])
+
+# Downloader side: verify before installing (raises IntegrityError on any mismatch).
+verify_manifest(module_dir, read_manifest(module_dir / "manifest.json"))
+```
+
+All hashes are SHA-256, lowercase hex, prefixed `sha256:`. The `artifact.digest` is a Merkle-style
+root over the canonical file listing — verifying it verifies the whole set and is the version's
+immutable content identity.
+
+## Develop
+
+```
+uv sync
+uv run pytest -vvv
+```

just_dna_format-0.1.0/README.md

@@ -0,0 +1,42 @@
+# just-dna-module
+
+The declarative **manifest contract** and **integrity primitives** for just-dna annotation
+modules. Dependency-light (Pydantic + stdlib only) so it can be shared as the single source of
+truth by both:
+
+- **`just-dna-pipelines`** — *emits* `manifest.json` when it compiles a module, and
+- **`just-dna-marketplace`** — *indexes, serves, and verifies* those manifests.
+
+Keeping the contract in one small package prevents the two sides from drifting.
+
+## What's here
+
+| Module | Contents |
+|---|---|
+| `just_dna_format.manifest` | `ModuleManifest` + sub-models (`Identity`, `Display`, `Stats`, `Compilation`, `FileEntry`, `Artifact`); `read_manifest` / `write_manifest`. Mirrors the marketplace SPEC §4. |
+| `just_dna_format.integrity` | `sha256_file`, `artifact_digest` (canonical Merkle root), `build_artifact`, `verify_manifest` (verify-then-install), `IntegrityError`. SPEC §5. |
+| `just_dna_format.identity` | Name/namespace rules, `canonical_id`, SemVer `Version` + `parse_version`, `version_from_legacy` (`vN → N.0.0`), `latest`. SPEC §6. |
+
+## Usage
+
+```python
+from just_dna_format.manifest import ModuleManifest, read_manifest
+from just_dna_format.integrity import build_artifact, verify_manifest
+
+# Compiler side: hash outputs and record the digest.
+artifact = build_artifact(output_dir, ["weights.parquet", "annotations.parquet", "studies.parquet"])
+
+# Downloader side: verify before installing (raises IntegrityError on any mismatch).
+verify_manifest(module_dir, read_manifest(module_dir / "manifest.json"))
+```
+
+All hashes are SHA-256, lowercase hex, prefixed `sha256:`. The `artifact.digest` is a Merkle-style
+root over the canonical file listing — verifying it verifies the whole set and is the version's
+immutable content identity.
+
+## Develop
+
+```
+uv sync
+uv run pytest -vvv
+```

just_dna_format-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "just-dna-format"
+version = "0.1.0"
+description = "Declarative schema + integrity contract for just-dna annotation modules (DSL spec, manifest, digests)"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.12.5",
+]
+
+[build-system]
+requires = ["uv-build"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

just_dna_format-0.1.0/src/just_dna_format/__init__.py

@@ -0,0 +1,15 @@
+"""
+just-dna-format — the declarative schema + integrity contract for just-dna annotation modules.
+
+Covers both halves of the module format: the authored input DSL (`spec`) and the compiled output
+`manifest` (+ integrity digests and identity/versioning rules). Dependency-light (Pydantic +
+stdlib) so it is shared by `just-dna-compiler` (which emits manifests), `just-dna-pipelines`, and
+`just-dna-marketplace` (which indexes and serves them) without pulling heavy transitive deps.
+
+Import from the submodules directly, e.g.::
+
+    from just_dna_format.spec import ModuleSpecConfig, VariantRow, StudyRow
+    from just_dna_format.manifest import ModuleManifest
+    from just_dna_format.integrity import sha256_file, artifact_digest, verify_manifest
+    from just_dna_format.identity import parse_version, canonical_id
+"""

just_dna_format-0.1.0/src/just_dna_format/identity.py

@@ -0,0 +1,100 @@
+"""
+Identity and versioning (SPEC §6).
+
+Identity is `namespace/name`. `name` keeps the DSL rule `^[a-z][a-z0-9_]*$`; `namespace` is an
+owned account/org slug (lowercase alphanumeric with hyphens, e.g. `just-dna-seq`). Versions are
+SemVer `MAJOR.MINOR.PATCH` for public ordering; the legacy `vN` directory convention maps
+`v1 -> 1.0.0`, `v2 -> 2.0.0`.
+"""
+
+import re
+from dataclasses import dataclass
+from functools import total_ordering
+
+NAME_PATTERN: re.Pattern[str] = re.compile(r"^[a-z][a-z0-9_]*$")
+NAMESPACE_PATTERN: re.Pattern[str] = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+_VERSION_PATTERN: re.Pattern[str] = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+_LEGACY_PATTERN: re.Pattern[str] = re.compile(r"^v?(\d+)$")
+
+
+def is_valid_name(name: str) -> bool:
+    """Whether `name` matches the module name rule `^[a-z][a-z0-9_]*$`."""
+    return bool(NAME_PATTERN.match(name))
+
+
+def validate_name(name: str) -> str:
+    """Return `name` if valid, else raise `ValueError`."""
+    if not is_valid_name(name):
+        raise ValueError(
+            f"module name must be lowercase alphanumeric with underscores, got: {name!r}"
+        )
+    return name
+
+
+def is_valid_namespace(namespace: str) -> bool:
+    """Whether `namespace` is a valid account/org slug (lowercase alnum + hyphens)."""
+    return bool(NAMESPACE_PATTERN.match(namespace))
+
+
+def validate_namespace(namespace: str) -> str:
+    """Return `namespace` if valid, else raise `ValueError`."""
+    if not is_valid_namespace(namespace):
+        raise ValueError(
+            f"namespace must be lowercase alphanumeric with hyphens, got: {namespace!r}"
+        )
+    return namespace
+
+
+def canonical_id(namespace: str, name: str, version: str) -> str:
+    """Build the canonical id `namespace/name@version`."""
+    return f"{namespace}/{name}@{version}"
+
+
+@total_ordering
+@dataclass(frozen=True)
+class Version:
+    """A parsed SemVer `MAJOR.MINOR.PATCH`, comparable and stringifiable."""
+
+    major: int
+    minor: int
+    patch: int
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+    @property
+    def as_tuple(self) -> tuple[int, int, int]:
+        return (self.major, self.minor, self.patch)
+
+    def __lt__(self, other: "Version") -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self.as_tuple < other.as_tuple
+
+
+def parse_version(version: str) -> Version:
+    """Parse a strict `MAJOR.MINOR.PATCH` string into a `Version`, else raise `ValueError`."""
+    match = _VERSION_PATTERN.match(version)
+    if match is None:
+        raise ValueError(f"version must be MAJOR.MINOR.PATCH, got: {version!r}")
+    return Version(int(match.group(1)), int(match.group(2)), int(match.group(3)))
+
+
+def is_valid_version(version: str) -> bool:
+    """Whether `version` is a strict `MAJOR.MINOR.PATCH` string."""
+    return bool(_VERSION_PATTERN.match(version))
+
+
+def version_from_legacy(legacy: str) -> str:
+    """Map a legacy integer or `vN` directory name to SemVer (`v1`/`1` -> `1.0.0`)."""
+    match = _LEGACY_PATTERN.match(legacy)
+    if match is None:
+        raise ValueError(f"legacy version must be an integer or vN, got: {legacy!r}")
+    return f"{int(match.group(1))}.0.0"
+
+
+def latest(versions: list[str]) -> str:
+    """Return the highest SemVer string from a non-empty list."""
+    if not versions:
+        raise ValueError("cannot pick latest from an empty version list")
+    return str(max((parse_version(v) for v in versions)))

just_dna_format-0.1.0/src/just_dna_format/integrity.py

@@ -0,0 +1,151 @@
+"""
+Integrity primitives (SPEC §5).
+
+All hashes are SHA-256, lowercase hex, prefixed `sha256:`. These functions are the shared
+implementation the compiler uses to *emit* integrity fields and a downloader uses to *verify*
+them — keeping both sides byte-for-byte agreement by construction.
+
+Time is never read here: callers pass any timestamps into the manifest. This keeps the module
+pure and deterministic.
+"""
+
+import hashlib
+import json
+from pathlib import Path
+
+from just_dna_format.manifest import (
+    MARKETPLACE_COMPILED_BY,
+    Artifact,
+    FileEntry,
+    ModuleManifest,
+)
+
+SHA256_PREFIX: str = "sha256:"
+_CHUNK: int = 1 << 20  # 1 MiB streaming reads
+
+
+class IntegrityError(Exception):
+    """Raised when a file hash, artifact digest, or trust check fails verification."""
+
+
+def sha256_bytes(data: bytes) -> str:
+    """SHA-256 of raw bytes, prefixed `sha256:`."""
+    return SHA256_PREFIX + hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    """Streaming SHA-256 of a file's raw bytes, prefixed `sha256:`."""
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        for chunk in iter(lambda: handle.read(_CHUNK), b""):
+            digest.update(chunk)
+    return SHA256_PREFIX + digest.hexdigest()
+
+
+def file_entry(directory: Path, name: str) -> FileEntry:
+    """Build a `FileEntry` (name, sha256, size) for `directory/name`."""
+    path = Path(directory) / name
+    return FileEntry(name=name, sha256=sha256_file(path), size=path.stat().st_size)
+
+
+def file_entries(directory: Path, names: list[str]) -> list[FileEntry]:
+    """Build `FileEntry` rows for each existing name under `directory` (skips missing)."""
+    directory = Path(directory)
+    return [file_entry(directory, name) for name in names if (directory / name).is_file()]
+
+
+def artifact_digest(files: list[FileEntry]) -> str:
+    """
+    Merkle-style root over the file set (SPEC §5): build the JSON array
+    `[{"name","sha256","size"}, ...]` sorted by name, serialized with sorted keys and no
+    whitespace, then hash. Verifying this one digest verifies the whole set, and it is the
+    version's immutable content identity — independent of the order files were listed in.
+    """
+    listing = sorted(
+        ({"name": f.name, "sha256": f.sha256, "size": f.size} for f in files),
+        key=lambda entry: entry["name"],
+    )
+    canonical = json.dumps(listing, sort_keys=True, separators=(",", ":"))
+    return sha256_bytes(canonical.encode("utf-8"))
+
+
+def build_artifact(output_dir: Path, filenames: list[str]) -> Artifact:
+    """Hash each output file and compute the artifact digest over the set."""
+    files = file_entries(output_dir, filenames)
+    return Artifact(digest=artifact_digest(files), files=files)
+
+
+def verify_manifest(
+    module_dir: Path,
+    manifest: ModuleManifest,
+    *,
+    require_marketplace: bool = True,
+    check_inputs: bool = False,
+    check_logs: bool = False,
+) -> None:
+    """
+    Verify a downloaded module against its manifest (SPEC §5 verify-then-install).
+
+    Steps:
+      1. Every `artifact.files[]` present on disk hashes to its declared value.
+      2. The recomputed `artifact.digest` matches the manifest.
+      3. `compile_success` is true and `compiled_by == "marketplace-server"`
+         (when `require_marketplace`).
+      4. Optionally (`check_inputs`) every `inputs[]` file on disk matches its declared hash.
+      5. Optionally (`check_logs`) every `logs[]` file *present* on disk matches its declared hash;
+         absent logs are skipped, since logs are optional and need not be downloaded.
+
+    Raises `IntegrityError` on the first failure; returns `None` on success.
+    """
+    module_dir = Path(module_dir)
+
+    for entry in manifest.artifact.files:
+        path = module_dir / entry.name
+        if not path.is_file():
+            raise IntegrityError(f"artifact file missing on disk: {entry.name}")
+        actual = sha256_file(path)
+        if actual != entry.sha256:
+            raise IntegrityError(
+                f"artifact hash mismatch for {entry.name}: "
+                f"declared {entry.sha256}, computed {actual}"
+            )
+
+    recomputed = artifact_digest(manifest.artifact.files)
+    if recomputed != manifest.artifact.digest:
+        raise IntegrityError(
+            f"artifact digest mismatch: declared {manifest.artifact.digest}, "
+            f"computed {recomputed}"
+        )
+
+    if require_marketplace:
+        if not manifest.compilation.compile_success:
+            raise IntegrityError("compilation.compile_success is not true — untrusted")
+        if manifest.compilation.compiled_by != MARKETPLACE_COMPILED_BY:
+            raise IntegrityError(
+                f"compiled_by is {manifest.compilation.compiled_by!r}, "
+                f"expected {MARKETPLACE_COMPILED_BY!r} — untrusted"
+            )
+
+    if check_inputs:
+        for entry in manifest.inputs:
+            path = module_dir / entry.name
+            if not path.is_file():
+                raise IntegrityError(f"input file missing on disk: {entry.name}")
+            actual = sha256_file(path)
+            if actual != entry.sha256:
+                raise IntegrityError(
+                    f"input hash mismatch for {entry.name}: "
+                    f"declared {entry.sha256}, computed {actual}"
+                )
+
+    if check_logs:
+        for entry in manifest.logs:
+            path = module_dir / entry.name
+            if not path.is_file():
+                continue  # logs are optional — an absent one is not a failure
+            actual = sha256_file(path)
+            if actual != entry.sha256:
+                raise IntegrityError(
+                    f"log hash mismatch for {entry.name}: "
+                    f"declared {entry.sha256}, computed {actual}"
+                )

just_dna_format-0.1.0/src/just_dna_format/manifest.py

@@ -0,0 +1,173 @@
+"""
+The `manifest.json` contract — the single source of truth for a compiled annotation module.
+
+Mirrors SPEC §4. Fields known at compile time (display, stats, compilation, inputs, artifact)
+are filled by the compiler; marketplace-level fields (namespace, version, owner, license,
+published_at, canonical_id) are `Optional` and filled by the marketplace on publish.
+
+This module is intentionally dependency-light (Pydantic + stdlib only) so both
+`just-dna-pipelines` (which emits the manifest) and `just-dna-marketplace` (which consumes and
+extends it) can share one definition without pulling heavy transitive dependencies.
+"""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from just_dna_format.identity import (
+    is_valid_version,
+    validate_name,
+    validate_namespace,
+)
+
+MANIFEST_VERSION: str = "1.0"
+SCHEMA_VERSION: str = "1.0"
+
+# The only `compiled_by` value a downloader trusts (SPEC §5).
+MARKETPLACE_COMPILED_BY: str = "marketplace-server"
+
+# Mirrors just-dna-pipelines ModuleInfo.color validation (module_compiler/models.py).
+COLOR_PATTERN: re.Pattern[str] = re.compile(r"^#[0-9a-fA-F]{6}$")
+
+
+class Identity(BaseModel):
+    """Module identity. `namespace`/`version`/`canonical_id` are filled by the marketplace.
+
+    Identity rules are validated here using the shared `just_dna_format.identity` helpers, so
+    the contract enforces exactly what just-dna-pipelines enforces on `module_spec.yaml`.
+    """
+
+    namespace: Optional[str] = Field(default=None, description="Owning account/org slug")
+    name: str = Field(description="Machine name, matches ^[a-z][a-z0-9_]*$")
+    version: Optional[str] = Field(default=None, description="SemVer MAJOR.MINOR.PATCH")
+    canonical_id: Optional[str] = Field(
+        default=None, description="namespace/name@version"
+    )
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, v: str) -> str:
+        return validate_name(v)
+
+    @field_validator("namespace")
+    @classmethod
+    def _check_namespace(cls, v: Optional[str]) -> Optional[str]:
+        return None if v is None else validate_namespace(v)
+
+    @field_validator("version")
+    @classmethod
+    def _check_version(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and not is_valid_version(v):
+            raise ValueError(f"version must be MAJOR.MINOR.PATCH, got: {v!r}")
+        return v
+
+
+class Display(BaseModel):
+    """Shared display metadata for a module. The authoring DSL's `spec.ModuleInfo` extends this
+    (adding `name`), so the fields and their validation are defined here once."""
+
+    title: str
+    description: str
+    report_title: str
+    icon: str = Field(default="database", description="Fomantic UI icon name")
+    color: str = Field(default="#6435c9", description="Hex color for UI theming")
+
+    @field_validator("color")
+    @classmethod
+    def _check_color(cls, v: str) -> str:
+        if not COLOR_PATTERN.match(v):
+            raise ValueError(f"color must be a 6-digit hex code like #21ba45, got: {v!r}")
+        return v
+
+
+class Stats(BaseModel):
+    """Card/detail stats derived from the spec at compile time."""
+
+    variant_count: int = 0
+    weights_rows: int = 0
+    study_count: int = 0
+    gene_count: int = 0
+    genes: list[str] = Field(default_factory=list)
+    categories: list[str] = Field(default_factory=list)
+
+
+class Compilation(BaseModel):
+    """Provenance of the compile that produced this artifact (SPEC §5 trust fields)."""
+
+    compile_success: bool = False
+    compiled_by: Optional[str] = Field(
+        default=None, description="e.g. 'marketplace-server'; foreign values are untrusted"
+    )
+    compiler_version: Optional[str] = None
+    ensembl_reference: Optional[str] = Field(
+        default=None, description="Pinned Ensembl reference, e.g. org/repo@<rev>"
+    )
+    compiled_at: Optional[str] = Field(default=None, description="ISO-8601 UTC timestamp")
+    warnings: list[str] = Field(default_factory=list)
+
+
+class FileEntry(BaseModel):
+    """One hashed file — used for both `inputs[]` and `artifact.files[]` (SPEC §5)."""
+
+    name: str
+    sha256: str = Field(description="Lowercase hex digest, prefixed 'sha256:'")
+    size: int = Field(description="Byte size of the file")
+
+
+class Artifact(BaseModel):
+    """The compiled output set plus its Merkle-root digest (the content identity)."""
+
+    digest: str = Field(description="sha256: over the canonical file listing (SPEC §5)")
+    files: list[FileEntry] = Field(default_factory=list)
+
+
+class ModuleManifest(BaseModel):
+    """Full module manifest (SPEC §4). Written next to the parquets as `manifest.json`."""
+
+    manifest_version: str = MANIFEST_VERSION
+    schema_version: str = SCHEMA_VERSION
+
+    identity: Identity
+    display: Display
+
+    genome_build: str = "GRCh38"
+    curator: Optional[str] = None
+    method: Optional[str] = None
+    license: Optional[str] = None
+
+    owner: Optional[str] = None
+    authors: list[str] = Field(default_factory=list)
+    created_at: Optional[str] = None
+    published_at: Optional[str] = None
+
+    stats: Stats = Field(default_factory=Stats)
+    compilation: Compilation = Field(default_factory=Compilation)
+    inputs: list[FileEntry] = Field(default_factory=list)
+    artifact: Artifact
+    logs: list[FileEntry] = Field(
+        default_factory=list,
+        description=(
+            "Optional per-version run/provenance log files, hashed like inputs. Each `name` is a "
+            "path relative to the module dir, so both a top-level aggregate log (e.g. `run.log`) "
+            "and per-role files under a `logs/` folder (e.g. `logs/researcher.log`, "
+            "`logs/reviewer.log`) are supported. Absent logs do NOT invalidate a module. Kept out "
+            "of `artifact.digest` so identical compiled data stays dedup-equal regardless of logs; "
+            "full cross-version provenance is the union of every version's logs."
+        ),
+    )
+
+
+def read_manifest(path: Path) -> ModuleManifest:
+    """Load and validate a `manifest.json` from disk."""
+    return ModuleManifest.model_validate_json(Path(path).read_text(encoding="utf-8"))
+
+
+def write_manifest(manifest: ModuleManifest, path: Path) -> Path:
+    """Write a manifest to disk as indented JSON. Returns the path written."""
+    path = Path(path)
+    path.write_text(
+        manifest.model_dump_json(indent=2, exclude_none=False) + "\n", encoding="utf-8"
+    )
+    return path

just_dna_format-0.1.0/src/just_dna_format/spec.py

@@ -0,0 +1,209 @@
+"""
+The authored module spec DSL (`module_spec.yaml` + `variants.csv` + `studies.csv`).
+
+This is the *input* half of the module format; `manifest.py` is the *output* half. Both live in
+this dependency-light package so the compiler is a pure transform between two validated schema
+sets, and any consumer can validate a spec or a manifest without pulling the compiler's polars/
+duckdb weight.
+
+Identity/display rules reuse the shared helpers in `identity` and `manifest`, so the DSL and the
+manifest enforce exactly the same constraints.
+"""
+
+import re
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from just_dna_format.identity import validate_name
+from just_dna_format.manifest import SCHEMA_VERSION, Display
+
+VALID_STATES: frozenset[str] = frozenset(
+    {"risk", "protective", "neutral", "significant", "alt", "ref"}
+)
+VALID_CHROMOSOMES: frozenset[str] = frozenset(
+    {str(i) for i in range(1, 23)} | {"X", "Y", "MT"}
+)
+RSID_PATTERN: re.Pattern[str] = re.compile(r"^rs\d+$")
+ALLELE_PATTERN: re.Pattern[str] = re.compile(r"^[ACGT]+$", re.IGNORECASE)
+
+
+class ModuleInfo(Display):
+    """The `module:` block of module_spec.yaml: a machine `name` plus the shared `Display`
+    metadata (title/description/report_title/icon/color).
+
+    Extends the manifest's `Display` rather than re-declaring those fields, so the display schema
+    and its validation (e.g. the hex-colour rule) live in exactly one place. `name` lives here on
+    the authoring side; the manifest routes it into `Identity` instead.
+    """
+
+    name: str = Field(description="Machine name: lowercase, underscores, no spaces")
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, v: str) -> str:
+        return validate_name(v)
+
+
+class Defaults(BaseModel):
+    """Default values applied to variant rows when not explicitly set."""
+
+    curator: str = Field(default="ai-module-creator", description="Default curator identifier")
+    method: str = Field(default="literature-review", description="Default annotation method")
+    priority: Optional[str] = Field(default=None, description="Default priority level")
+
+
+class ModuleSpecConfig(BaseModel):
+    """Top-level model for module_spec.yaml."""
+
+    schema_version: str = Field(default=SCHEMA_VERSION, description="DSL schema version")
+    module: ModuleInfo = Field(description="Module identity and display metadata")
+    defaults: Defaults = Field(default_factory=Defaults, description="Default variant-row values")
+    genome_build: str = Field(default="GRCh38", description="Reference genome build for positions")
+
+    @field_validator("schema_version")
+    @classmethod
+    def _validate_version(cls, v: str) -> str:
+        if v != SCHEMA_VERSION:
+            raise ValueError(f"Unsupported schema_version: {v!r}. Expected {SCHEMA_VERSION!r}")
+        return v
+
+
+class VariantRow(BaseModel):
+    """One row of variants.csv. At least one identifier (rsid or chrom+start) is required."""
+
+    rsid: Optional[str] = Field(default=None, description="dbSNP identifier, e.g. rs1801133")
+    chrom: Optional[str] = Field(default=None, description="Chromosome without 'chr' prefix")
+    start: Optional[int] = Field(default=None, description="0-based genomic position (GRCh38)")
+    ref: Optional[str] = Field(default=None, description="Reference allele")
+    alts: Optional[str] = Field(default=None, description="Alt allele(s), comma-separated")
+    genotype: str = Field(description="Slash-separated sorted alleles, e.g. A/G")
+    weight: Optional[float] = Field(default=None, description="Score (positive=protective)")
+    state: str = Field(description="One of: risk, protective, neutral, significant, alt, ref")
+    conclusion: str = Field(description="Human-readable interpretation for this genotype")
+    priority: Optional[str] = Field(default=None, description="Priority level override")
+    gene: Optional[str] = Field(default=None, description="Gene symbol, e.g. MTHFR")
+    phenotype: Optional[str] = Field(default=None, description="Associated trait or phenotype")
+    category: Optional[str] = Field(default=None, description="Grouping category within the module")
+    clinvar: Optional[bool] = Field(default=None, description="Is this variant in ClinVar?")
+    pathogenic: Optional[bool] = Field(default=None, description="ClinVar pathogenic flag")
+    benign: Optional[bool] = Field(default=None, description="ClinVar benign flag")
+    curator: Optional[str] = Field(default=None, description="Curator override")
+    method: Optional[str] = Field(default=None, description="Annotation method override")
+
+    @property
+    def variant_key(self) -> str:
+        """Stable grouping key: rsid when available, else chrom:start:ref."""
+        if self.rsid is not None:
+            return self.rsid
+        return f"{self.chrom}:{self.start}:{self.ref}"
+
+    @field_validator("rsid")
+    @classmethod
+    def _validate_rsid(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and not RSID_PATTERN.match(v):
+            raise ValueError(f"rsid must match rs<digits>, got: {v!r}")
+        return v
+
+    @field_validator("state")
+    @classmethod
+    def _validate_state(cls, v: str) -> str:
+        if v not in VALID_STATES:
+            raise ValueError(f"state must be one of {sorted(VALID_STATES)}, got: {v!r}")
+        return v
+
+    @field_validator("chrom")
+    @classmethod
+    def _validate_chrom(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None:
+            normalized = v.removeprefix("chr")
+            if normalized not in VALID_CHROMOSOMES:
+                raise ValueError(
+                    f"chrom must be one of 1-22, X, Y, MT (without 'chr' prefix), got: {v!r}"
+                )
+            return normalized
+        return v
+
+    @field_validator("genotype")
+    @classmethod
+    def _validate_genotype(cls, v: str) -> str:
+        parts = v.split("/")
+        if len(parts) != 2:
+            raise ValueError(f"genotype must be two alleles slash-separated (e.g. A/G), got: {v!r}")
+        for allele in parts:
+            if not ALLELE_PATTERN.match(allele):
+                raise ValueError(
+                    f"genotype alleles must be uppercase nucleotides, got: {allele!r} in {v!r}"
+                )
+        if parts != sorted(parts):
+            raise ValueError(
+                f"genotype alleles must be alphabetically sorted: "
+                f"expected {'/'.join(sorted(parts))!r}, got: {v!r}"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _validate_identification(self) -> "VariantRow":
+        has_rsid = self.rsid is not None
+        positional = {"chrom": self.chrom, "start": self.start}
+        has_pos = any(v is not None for v in positional.values())
+        has_ref = any(v is not None for v in {"ref": self.ref, "alts": self.alts}.values())
+
+        if not has_rsid and not has_pos:
+            raise ValueError(
+                "At least one identifier is required: provide rsid or position (chrom + start)"
+            )
+        if has_pos:
+            missing = [k for k, v in positional.items() if v is None]
+            if missing:
+                raise ValueError(
+                    f"If any positional columns are provided, chrom and start are required. "
+                    f"Missing: {missing}"
+                )
+        if has_ref and not has_pos:
+            raise ValueError("ref/alts require chrom and start to also be provided")
+        return self
+
+
+class StudyRow(BaseModel):
+    """One row of studies.csv: an (rsid, pmid) evidence link. Grounding evidence is mandatory."""
+
+    rsid: Optional[str] = Field(default=None, description="dbSNP identifier or variant key")
+    chrom: Optional[str] = Field(default=None, description="Chromosome (for position-only variants)")
+    start: Optional[int] = Field(default=None, description="0-based position (position-only variants)")
+    ref: Optional[str] = Field(default=None, description="Reference allele (position-only variants)")
+    pmid: str = Field(description="PubMed ID or reference — free-form, must be non-empty")
+    population: Optional[str] = Field(default=None, description="Study population")
+    p_value: Optional[str] = Field(default=None, description="Statistical significance")
+    conclusion: Optional[str] = Field(default=None, description="Study-specific conclusion")
+    study_design: Optional[str] = Field(default=None, description="e.g. meta-analysis, GWAS")
+
+    @property
+    def variant_key(self) -> str:
+        """Stable key matching VariantRow.variant_key."""
+        if self.rsid is not None:
+            return self.rsid
+        return f"{self.chrom}:{self.start}:{self.ref}"
+
+    @field_validator("rsid")
+    @classmethod
+    def _validate_rsid(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and not RSID_PATTERN.match(v):
+            raise ValueError(f"rsid must match rs<digits>, got: {v!r}")
+        return v
+
+    @field_validator("pmid")
+    @classmethod
+    def _validate_pmid(cls, v: str) -> str:
+        v = str(v).strip()
+        if not v:
+            raise ValueError("pmid must not be empty")
+        return v
+
+    @model_validator(mode="after")
+    def _validate_study_identification(self) -> "StudyRow":
+        if self.rsid is None and self.chrom is None:
+            raise ValueError(
+                "At least one identifier is required: provide rsid or position (chrom + start)"
+            )
+        return self