reprovane 2.0.0__py3-none-any.whl

reprovane/__init__.py

@@ -0,0 +1 @@
+from ._version import __version__

reprovane/__main__.py

@@ -0,0 +1,105 @@
+"""Thin discoverable router; scientific operations stay in their accepted modules."""
+import argparse,importlib,json,sys
+from pathlib import Path
+from . import __version__
+from .core import ValidationError,ArtifactIntegrityError,MigrationDriftError,FoundationError
+
+ROUTES={'acquisition':'openalex_acquisition','venue-data':'venue_intelligence','discovery':'discovery','frontier':'frontier','search-validation':'search_validation','screening':'screening','corpus':'corpus_release','fulltext':'fulltext_acquisition'}
+
+
+def main(argv=None):
+    args=list(sys.argv[1:] if argv is None else argv)
+    if args and args[0] in ROUTES:return importlib.import_module('reprovane.'+ROUTES[args[0]]+'.__main__').main(args[1:])
+    parser=argparse.ArgumentParser(prog='reprovane',description='Reprovane — reproducible literature discovery, screening, evidence management, corpus release, and full-text acquisition.')
+    parser.add_argument('--version',action='version',version=__version__);sub=parser.add_subparsers(dest='family',required=True)
+    for family,module in ROUTES.items():sub.add_parser(family,help='Existing '+module+' CLI (use '+family+' --help)')
+    for name in ('doctor','verify','inspect'):
+        p=sub.add_parser(name);p.add_argument('--offline',action='store_true',default=True);p.add_argument('--workspace',type=Path);p.add_argument('--full',action='store_true')
+    p=sub.add_parser('workspace');s=p.add_subparsers(dest='command',required=True)
+    i=s.add_parser('init');i.add_argument('--workspace',type=Path,required=True)
+    i=s.add_parser('upgrade');i.add_argument('--workspace',type=Path,required=True);i.add_argument('--target',type=Path,required=True);i.add_argument('--backup',type=Path,required=True)
+    p=sub.add_parser('legacy');s=p.add_subparsers(dest='command',required=True)
+    for cmd in ('audit','plan','migrate','verify','inspect'):
+        i=s.add_parser(cmd)
+        if cmd in ('audit','plan','migrate'):i.add_argument('--source',type=Path,required=True)
+        if cmd=='plan':i.add_argument('--project-key',default='legacy-v4-import');i.add_argument('--revision-number',type=int,default=1)
+        if cmd=='migrate':i.add_argument('--target',type=Path);i.add_argument('--plan',type=Path);i.add_argument('--dry-run',action='store_true')
+        if cmd in ('verify','inspect'):i.add_argument('--workspace',type=Path,required=True);i.add_argument('--migration-id',required=True);i.add_argument('--source',type=Path)
+    p=sub.add_parser('project');s=p.add_subparsers(dest='command',required=True)
+    for cmd in ('create','revision','inspect'):
+        i=s.add_parser(cmd);i.add_argument('--workspace',type=Path,required=True)
+        if cmd=='create':i.add_argument('--key',required=True);i.add_argument('--display-name',required=True)
+        else:i.add_argument('--project-id',required=True)
+        if cmd=='revision':i.add_argument('--number',type=int,required=True);i.add_argument('--manifest',type=Path,required=True)
+    for family in ('resolution','venue-resolution'):
+        p=sub.add_parser(family);s=p.add_subparsers(dest='command',required=True)
+        for cmd in ('create','add','generate','evaluate','materialize','seal','verify','inspect'):
+            i=s.add_parser(cmd);i.add_argument('--workspace',type=Path,required=True)
+            if cmd=='create':i.add_argument('--project-revision',required=True);i.add_argument('--selector',type=Path,required=True)
+            else:i.add_argument('--run-id',required=True)
+            if cmd=='add':i.add_argument('--record-id',action='append',required=True)
+    p=sub.add_parser('scimago');p.add_argument('--workspace',type=Path,required=True);p.add_argument('--ref',default='control');p.add_argument('--offline',action='store_true');p.add_argument('--import-snapshot',action='store_true')
+    a=parser.parse_args(args)
+    try:
+        result=dispatch(a)
+        print(json.dumps(result,ensure_ascii=False,sort_keys=True));return 0
+    except (ArtifactIntegrityError,MigrationDriftError):print('Integrity verification failed; private inputs are not printed.',file=sys.stderr);return 3
+    except (ValidationError,FoundationError,ValueError,OSError):print('Validation/configuration failed; inspect the offline doctor and immutable inputs.',file=sys.stderr);return 5 if a.family=='legacy' and a.command=='migrate' else 2
+    except Exception:
+        print('Operation failed safely; no private exception payload is printed.',file=sys.stderr)
+        return 4 if a.family=='scimago' else 5 if a.family=='legacy' and a.command=='migrate' else 2
+
+
+def dispatch(a):
+    from .operations.workspace import doctor,initialize,upgrade,read_database
+    from .operations.lock import workspace_lock
+    from .core.db import Database
+    if a.family in ('doctor','verify','inspect'):return doctor(a.workspace,full=a.full or a.family=='verify')
+    if a.family=='workspace':return initialize(a.workspace) if a.command=='init' else upgrade(a.workspace,a.target,a.backup)
+    if a.family=='legacy':
+        from .legacy_migration import audit,plan,execute,LegacyMigrationStore
+        if a.command=='audit':return audit(a.source)
+        if a.command=='plan':return plan(a.source,a.project_key,a.revision_number)
+        if a.command=='migrate':
+            if a.dry_run:return plan(a.source)
+            if a.target is None or a.plan is None:raise ValidationError('Execution requires saved plan and separate target')
+            return execute(a.source,a.target,json.loads(a.plan.read_text(encoding='utf-8-sig')))
+        with read_database(a.workspace) as db:
+            store=LegacyMigrationStore(db)
+            return store.verify(a.migration_id,a.source) if a.command=='verify' else store.get(a.migration_id)
+    if a.family=='scimago':
+        from .mirror import sync_scimago_from_github,import_synced_scimago
+        with workspace_lock(a.workspace):
+            result=sync_scimago_from_github(a.workspace,requested_ref=a.ref,offline=a.offline)
+            if a.import_snapshot:
+                with Database(a.workspace) as db:return import_synced_scimago(db,result)
+            from dataclasses import asdict
+            return asdict(result)
+    readonly=a.command in ('verify','inspect')
+    from contextlib import nullcontext
+    with (nullcontext() if readonly else workspace_lock(a.workspace)):
+        with (read_database(a.workspace) if readonly else Database(a.workspace)) as db:
+            if a.family=='project':
+                from .core.foundation import Foundation
+                f=Foundation(db)
+                if a.command=='create':return f.create_project(a.key,a.display_name)
+                if a.command=='revision':return f.create_project_revision(a.project_id,a.number,'json',a.manifest.read_text(encoding='utf-8-sig'))
+                return dict(project=f.get_project(a.project_id),revisions=f.list_project_revisions(a.project_id))
+            venue=a.family=='venue-resolution'
+            if venue:
+                from .venue_resolution import VenueResolutionStore
+                store=VenueResolutionStore(db);prefix='venue_resolution'
+            else:
+                from .resolution import ResolutionStore
+                store=ResolutionStore(db);prefix='resolution'
+            if a.command=='create':return getattr(store,'create_'+prefix+'_run')(a.project_revision,json.loads(a.selector.read_text(encoding='utf-8-sig')))
+            if a.command=='add':return getattr(store,'add_'+prefix+'_inputs')(a.run_id,a.record_id)
+            if a.command=='generate':
+                if venue:store.generate_provider_nodes(a.run_id)
+                return store.generate_candidates(a.run_id)
+            if a.command=='evaluate':return store.evaluate_candidates_automatically(a.run_id)
+            method={'materialize':'materialize_','seal':'seal_','verify':'verify_','inspect':'get_'}[a.command]+prefix+'_run'
+            return getattr(store,method)(a.run_id)
+
+
+if __name__=='__main__':raise SystemExit(main())

reprovane/_version.py

@@ -0,0 +1,3 @@
+"""Reprovane product version; predecessor version is provenance only."""
+__version__ = "2.0.0"
+LEGACY_PREDECESSOR_VERSION = "4.1.0"

reprovane/common.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+import re
+import unicodedata
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+
+def safe_str(value: Any) -> str:
+    return "" if value is None else str(value)
+
+
+def normalize_doi(doi: Optional[str]) -> str:
+    if not doi:
+        return ""
+    value = doi.strip().lower()
+    for prefix in (
+        "https://doi.org/",
+        "http://doi.org/",
+        "https://dx.doi.org/",
+        "http://dx.doi.org/",
+        "doi:",
+    ):
+        if value.startswith(prefix):
+            value = value[len(prefix):]
+            break
+    return value.strip()
+
+
+def short_openalex_id(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    return value.rstrip("/").split("/")[-1]
+
+
+def normalize_issn(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    return re.sub(r"[^0-9Xx]", "", value).upper()
+
+
+def split_issns(value: Optional[str]) -> List[str]:
+    if not value:
+        return []
+    parts = re.split(r"[;,|]", value)
+    result: List[str] = []
+    seen = set()
+    for part in parts:
+        normalized = normalize_issn(part)
+        if normalized and normalized not in seen:
+            seen.add(normalized)
+            result.append(normalized)
+    return result
+
+
+def title_exact_key(value: Optional[str]) -> str:
+    text = safe_str(value).casefold().strip()
+    return re.sub(r"\s+", " ", text)
+
+
+_NON_ALNUM_RE = re.compile(r"[^a-z0-9]+")
+
+
+def title_normalized_key(value: Optional[str]) -> str:
+    # "&" means "and" (OpenAlex "Computers & Security" vs SCImago "Computers and Security"); it was
+    # previously deleted like other punctuation, so such titles never matched without an ISSN.
+    text = safe_str(value).replace("&", " and ")
+    if not text.isascii():
+        # NFKD + combining-mark removal is a no-op for ASCII, so it only runs when needed.
+        text = unicodedata.normalize("NFKD", text)
+        text = "".join(ch for ch in text if not unicodedata.combining(ch))
+    text = text.casefold()
+    return _NON_ALNUM_RE.sub("", text)
+
+
+STATUS_SUFFIX_RE = re.compile(r"\s*\((?:discontinued|ceased)\)\s*$", re.IGNORECASE)
+
+
+def strip_status_suffix(value: Optional[str]) -> str:
+    """Remove SCImago status labels such as ' (discontinued)' from the end of a title."""
+    return STATUS_SUFFIX_RE.sub("", safe_str(value))
+
+
+def has_status_suffix(value: Optional[str]) -> bool:
+    return bool(STATUS_SUFFIX_RE.search(safe_str(value)))
+
+
+def title_status_normalized_key(value: Optional[str]) -> str:
+    return title_normalized_key(strip_status_suffix(value))
+
+
+VALID_QUARTILES = {"Q1", "Q2", "Q3", "Q4"}
+
+
+def normalize_quartile(value: Any) -> str:
+    """Return Q1-Q4, or "" for SCImago placeholders such as "-" (no quartile assigned)."""
+    text = safe_str(value).strip().upper()
+    return text if text in VALID_QUARTILES else ""
+
+
+_SECRET_PARAM_RE = re.compile(r"(?i)(api_key|apikey|access_token|token)=([^&\s'\"<>]+)")
+
+
+def redact_secrets(text: Any, *secrets: str) -> str:
+    """Mask credential query parameters and any literal secret values in a message."""
+    result = _SECRET_PARAM_RE.sub(lambda m: f"{m.group(1)}=REDACTED", safe_str(text))
+    for secret in secrets:
+        if secret:
+            result = result.replace(secret, "REDACTED")
+    return result
+
+
+def locale_float(value: Any) -> Optional[float]:
+    text = safe_str(value).strip()
+    if not text:
+        return None
+    text = text.replace(" ", "").replace(",", ".")
+    try:
+        return float(text)
+    except ValueError:
+        return None
+
+
+def int_or_none(value: Any) -> Optional[int]:
+    text = safe_str(value).strip().replace(" ", "")
+    if not text:
+        return None
+    try:
+        return int(float(text.replace(",", ".")))
+    except ValueError:
+        return None
+
+
+def sha256_file(path: Path, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def read_json(path: Path) -> Dict[str, Any]:
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(data, handle, ensure_ascii=False, indent=2)
+        handle.write("\n")
+
+
+def write_jsonl(path: Path, rows: Iterable[Dict[str, Any]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False))
+            handle.write("\n")
+
+
+def read_jsonl(path: Path) -> List[Dict[str, Any]]:
+    rows: List[Dict[str, Any]] = []
+    if not path.exists():
+        return rows
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+            rows.append(json.loads(line))
+    return rows
+
+
+def union_fieldnames(rows: Iterable[Dict[str, Any]]) -> List[str]:
+    ordered: List[str] = []
+    seen = set()
+    for row in rows:
+        for key in row.keys():
+            if key not in seen:
+                seen.add(key)
+                ordered.append(key)
+    return ordered
+
+
+def write_csv(path: Path, rows: List[Dict[str, Any]], fieldnames: Optional[List[str]] = None) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if fieldnames is None:
+        fieldnames = union_fieldnames(rows)
+    with path.open("w", encoding="utf-8-sig", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=fieldnames, extrasaction="ignore")
+        writer.writeheader()
+        for row in rows:
+            writer.writerow(row)
+
+
+def read_csv(path: Path) -> List[Dict[str, str]]:
+    with path.open("r", encoding="utf-8-sig", newline="") as handle:
+        return list(csv.DictReader(handle))

reprovane/config.py

@@ -0,0 +1,115 @@
+"""Optional private configuration file (config.json).
+
+Precedence for every setting: CLI argument > config.json > code default. For the OpenAlex API key
+only, the legacy OPENALEX_API_KEY environment variable is still honoured after config.json
+(deprecated, kept so existing v3.0.x setups do not break).
+
+config.json holds the API key, so it is validated strictly (unknown sections/keys, wrong types and
+values outside a fixed list are errors) and no error message ever echoes a value, or an unknown key
+name, from the file.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from .openalex import SEARCH_FIELDS
+
+CONFIG_FILENAME = "config.json"
+
+# section -> key -> allowed JSON types
+SCHEMA: Dict[str, Dict[str, Tuple[type, ...]]] = {
+    "openalex": {"api_key": (str,), "email": (str,)},
+    "scimago": {"manifest_url": (str,), "cache_dir": (str,)},
+    "run": {"from_year": (int,), "to_year": (int,), "require_abstract": (bool,), "max_per_query": (int, type(None)),
+            "search_field": (str,)},
+    # defaults for run and enrich: the venue list (--venue-tiers) and the tiers it admits (--admit-tier)
+    "screening": {"venue_tiers": (str,), "admit_tiers": (list,)},
+}
+# (section, key) -> allowed string values; an empty string still means "use the default"
+CHOICES: Dict[Tuple[str, str], Tuple[str, ...]] = {("run", "search_field"): SEARCH_FIELDS}
+_TYPE_NAMES = {str: "a string", int: "an integer", bool: "true/false", type(None): "null", list: "a list of strings"}
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass
+class Config:
+    path: Optional[Path] = None
+    data: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+
+    def get(self, section: str, key: str) -> Any:
+        """Configured value, or None when the file, section or key is absent or the string is empty."""
+        value = (self.data.get(section) or {}).get(key)
+        return None if value == "" else value
+
+    @property
+    def label(self) -> str:
+        """Name used in metadata/console as the source of a setting (never the value)."""
+        return self.path.name if self.path else ""
+
+
+def _type_ok(value: Any, allowed: Tuple[type, ...]) -> bool:
+    if isinstance(value, bool):  # bool is an int subclass: only accept it where bool is allowed
+        return bool in allowed
+    return isinstance(value, allowed)
+
+
+def load_config(explicit_path: Optional[Path], default_dir: Path) -> Config:
+    """Load `explicit_path`, else `<default_dir>/config.json` if it exists, else an empty Config."""
+    if explicit_path is not None:
+        path = Path(explicit_path)
+        if not path.is_file():
+            raise ConfigError(f"Config file not found: {path}")
+    else:
+        path = Path(default_dir) / CONFIG_FILENAME
+        if not path.is_file():
+            return Config()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path}: invalid JSON ({exc.msg} at line {exc.lineno}, column {exc.colno})") from None
+    except UnicodeDecodeError:
+        raise ConfigError(f"{path}: file is not UTF-8 text") from None
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{path}: the top level must be a JSON object")
+
+    data: Dict[str, Dict[str, Any]] = {}
+    for section, values in raw.items():
+        if section.startswith("_"):  # comment entries such as "_comment"
+            continue
+        if section not in SCHEMA:
+            raise ConfigError(f"{path}: unknown top-level section (allowed: {', '.join(SCHEMA)}, or names starting with '_')")
+        if not isinstance(values, dict):
+            raise ConfigError(f"{path}: section '{section}' must be a JSON object")
+        clean: Dict[str, Any] = {}
+        for key, value in values.items():
+            if key.startswith("_"):
+                continue
+            if key not in SCHEMA[section]:
+                raise ConfigError(f"{path}: unknown key in section '{section}' (allowed: {', '.join(SCHEMA[section])})")
+            allowed = SCHEMA[section][key]
+            if not _type_ok(value, allowed):
+                expected = " or ".join(_TYPE_NAMES[t] for t in allowed)
+                raise ConfigError(f"{path}: '{section}.{key}' must be {expected}")
+            if isinstance(value, list):
+                if not all(isinstance(item, str) and item.strip() for item in value):
+                    raise ConfigError(f"{path}: '{section}.{key}' must be a list of non-empty strings")
+                value = [item.strip() for item in value]
+            choices = CHOICES.get((section, key))
+            if choices and value.strip() and value.strip() not in choices:
+                raise ConfigError(f"{path}: '{section}.{key}' must be one of: {', '.join(choices)}")
+            clean[key] = value.strip() if isinstance(value, str) else value
+        data[section] = clean
+
+    # Relative paths are relative to the config file, not to the current directory.
+    for section, key in (("scimago", "cache_dir"), ("screening", "venue_tiers")):
+        value = (data.get(section) or {}).get(key)
+        if value:
+            resolved = Path(value).expanduser()
+            data[section][key] = str(resolved if resolved.is_absolute() else path.parent / resolved)
+    return Config(path=path, data=data)

reprovane/core/__init__.py

@@ -0,0 +1,29 @@
+"""Isolated standard-library persistence foundation; unused by the legacy CLI."""
+
+
+class FoundationError(Exception):
+    """Base error for foundation operations (messages contain no input values)."""
+
+
+class MigrationError(FoundationError):
+    pass
+
+
+class MigrationDriftError(MigrationError):
+    pass
+
+
+class ImmutabilityError(FoundationError):
+    pass
+
+
+class SnapshotSealedError(ImmutabilityError):
+    pass
+
+
+class ArtifactIntegrityError(FoundationError):
+    pass
+
+
+class ValidationError(FoundationError):
+    pass

reprovane/core/artifacts.py

@@ -0,0 +1,100 @@
+"""Immutable exact-byte SHA-256 objects. Placement precedes database registration."""
+import hashlib
+import os
+import re
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO
+
+from . import ArtifactIntegrityError, ValidationError
+
+
+@dataclass(frozen=True)
+class StoredArtifact:
+    artifact_sha256: str
+    byte_size: int
+    relative_path: str
+
+
+class ContentAddressedArtifactStore:
+    def __init__(self, workspace: Path):
+        self.workspace = Path(workspace).resolve()
+        self.root = self.workspace / "raw" / "sha256"
+
+    def path_for_hash(self, digest: str) -> Path:
+        if not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest):
+            raise ValidationError("Invalid artifact SHA-256")
+        path = self.root / digest[:2] / digest
+        if not path.resolve().is_relative_to(self.workspace):
+            raise ValidationError("Artifact path escapes workspace")
+        return path
+
+    def verify(self, digest: str) -> StoredArtifact:
+        path = self.path_for_hash(digest)
+        try:
+            hasher = hashlib.sha256()
+            size = 0
+            with path.open("rb") as handle:
+                for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                    hasher.update(chunk)
+                    size += len(chunk)
+            if hasher.hexdigest() != digest:
+                raise ArtifactIntegrityError("Artifact hash mismatch")
+            return StoredArtifact(digest, size, path.relative_to(self.workspace).as_posix())
+        except OSError:
+            raise ArtifactIntegrityError("Artifact missing or unreadable") from None
+
+    @staticmethod
+    def _sync_directory(path: Path) -> None:
+        # Windows does not expose a portable directory fsync; file fsync is still mandatory.
+        if os.name == "posix":
+            fd = os.open(path, os.O_RDONLY)
+            try:
+                os.fsync(fd)
+            finally:
+                os.close(fd)
+
+    def _put_stream(self, stream: BinaryIO) -> StoredArtifact:
+        # Staging shares the destination filesystem. No user locator enters a filename.
+        if not self.root.resolve().is_relative_to(self.workspace):
+            raise ValidationError("Artifact directory escapes workspace")
+        self.root.mkdir(parents=True, exist_ok=True)
+        tmp: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(dir=self.root, prefix=".put-", delete=False) as handle:
+                tmp = Path(handle.name)
+                digest = hashlib.sha256()
+                for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                    digest.update(chunk)
+                    handle.write(chunk)
+                handle.flush()
+                os.fsync(handle.fileno())
+            key = digest.hexdigest()
+            target = self.path_for_hash(key)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if target.exists():
+                return self.verify(key)
+            os.replace(tmp, target)
+            # Persist the new file entry AND newly created shard/root directory entries.
+            for folder in (target.parent, self.root, self.root.parent, self.workspace):
+                self._sync_directory(folder)
+            return self.verify(key)
+        except OSError:
+            raise ArtifactIntegrityError("Artifact placement failed") from None
+        finally:
+            if tmp is not None:
+                tmp.unlink(missing_ok=True)
+
+    def put_bytes(self, data: bytes) -> StoredArtifact:
+        from io import BytesIO
+        if not isinstance(data, bytes):
+            raise ValidationError("Artifact input must be bytes")
+        return self._put_stream(BytesIO(data))
+
+    def put_file(self, path: Path) -> StoredArtifact:
+        try:
+            with Path(path).open("rb") as handle:
+                return self._put_stream(handle)
+        except OSError:
+            raise ArtifactIntegrityError("Artifact source missing or unreadable") from None

reprovane/core/db.py

@@ -0,0 +1,78 @@
+"""Explicit SQLite durability/transaction boundary; one connection per Database."""
+import hashlib
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+from . import FoundationError, ImmutabilityError, SnapshotSealedError, ValidationError
+from .migrations import MIGRATION_DIR, apply_migrations
+from .provenance import sanitize_locator
+
+
+class Database:
+    def __init__(self, workspace: Path, *, migration_dir: Path = MIGRATION_DIR, target_schema_version: int = 1):
+        self.workspace = Path(workspace).resolve()
+        folder = self.workspace / "db"
+        folder.mkdir(parents=True, exist_ok=True)
+        if not folder.resolve().is_relative_to(self.workspace):
+            raise ValidationError("Database directory escapes workspace")
+        self.path = folder / "litintel.sqlite"
+        if not self.path.resolve().is_relative_to(self.workspace):
+            raise ValidationError("Database path escapes workspace")
+        self._sealing_snapshot: str | None = None
+        self.connection = sqlite3.connect(self.path, isolation_level=None, timeout=5.0)
+        self.connection.row_factory = sqlite3.Row
+        self.connection.create_function("foundation_seal_authorized", 1,
+                                        lambda sid: int(sid == self._sealing_snapshot))
+        self.connection.create_function("foundation_sha256_text", 1,
+                                        lambda text: hashlib.sha256(text.encode("utf-8")).hexdigest(), deterministic=True)
+        self.connection.create_function("foundation_sanitize_locator", 1, sanitize_locator, deterministic=True)
+        try:
+            self.connection.execute("PRAGMA foreign_keys = ON")
+            mode = self.connection.execute("PRAGMA journal_mode = WAL").fetchone()[0]
+            self.connection.execute("PRAGMA synchronous = FULL")
+            self.connection.execute("PRAGMA busy_timeout = 5000")
+            # REPLACE must fire delete guards too; otherwise it could bypass immutable-row triggers.
+            self.connection.execute("PRAGMA recursive_triggers = ON")
+            if mode.lower() != "wal" or self.connection.execute("PRAGMA foreign_keys").fetchone()[0] != 1:
+                raise FoundationError("Required SQLite durability settings unavailable")
+            apply_migrations(self.connection, migration_dir, target_version=target_schema_version)
+        except Exception:
+            self.connection.close()
+            raise
+
+    def execute(self, sql: str, parameters: Any = ()) -> sqlite3.Cursor:
+        try:
+            return self.connection.execute(sql, parameters)
+        except sqlite3.IntegrityError as exc:
+            message = str(exc)
+            if "snapshot sealed" in message:
+                raise SnapshotSealedError("Snapshot is sealed") from None
+            if "immutable" in message or "seal transition" in message:
+                raise ImmutabilityError("Immutable object or unauthorized seal transition") from None
+            raise ValidationError("Database constraint rejected the operation") from None
+        except sqlite3.DatabaseError:
+            raise FoundationError("Database operation failed") from None
+
+    @contextmanager
+    def transaction(self) -> Iterator[None]:
+        if self.connection.in_transaction:
+            raise FoundationError("Nested transactions are unsupported; reuse the active transaction")
+        self.execute("BEGIN IMMEDIATE")
+        try:
+            yield
+            self.execute("COMMIT")
+        except BaseException:
+            if self.connection.in_transaction:
+                self.connection.execute("ROLLBACK")
+            raise
+
+    def close(self) -> None:
+        self.connection.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()