xtalate 0.1.0.dev0__tar.gz

xtalate-0.1.0.dev0/.claude/settings.local.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -n '^#\\\\{1,3\\\\} ' /Users/ailsayilu/ChemBridge/docs/MASTER_SPEC.md)",
+      "Bash(python3 -m venv /tmp/cb-venv)",
+      "Bash(/tmp/cb-venv/bin/python -m pip install --upgrade pip -q)",
+      "Bash(/tmp/cb-venv/bin/pip install *)",
+      "Bash(/tmp/cb-venv/bin/ruff check *)",
+      "Bash(/tmp/cb-venv/bin/ruff format *)",
+      "Bash(/tmp/cb-venv/bin/mypy)",
+      "Bash(/tmp/cb-venv/bin/lint-imports)",
+      "Bash(/tmp/cb-venv/bin/pytest -q)",
+      "Bash(/tmp/cb-venv/bin/chembridge)",
+      "Bash(git checkout *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(rm -rf /tmp/cb-venv && echo \"venv removed\" && git log --oneline -1 && git branch --show-current)",
+      "Bash(pip show *)",
+      "Bash(python3 -m venv .venv)",
+      "Bash(.venv/bin/python -m pip install --upgrade pip -q)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(.venv/bin/python --version)",
+      "Bash(.venv/bin/python -c \"import chembridge; print\\('chembridge', chembridge.__version__, 'importable from', chembridge.__file__\\)\")",
+      "Bash(.venv/bin/ruff check *)",
+      "Bash(.venv/bin/ruff format *)",
+      "Bash(.venv/bin/mypy)",
+      "Bash(.venv/bin/lint-imports)",
+      "Bash(.venv/bin/pytest -q)",
+      "Bash(.venv/bin/python -c \"import yaml,sys\")",
+      "Bash(.venv/bin/python -c \"import yaml; d=yaml.safe_load\\(open\\('.github/workflows/ci.yml'\\)\\); print\\(' matrix:', d['jobs']['lint-and-test']['strategy']['matrix']['python-version']\\)\")",
+      "Bash(python3 -c \"import yaml; d=yaml.safe_load\\(open\\('.github/workflows/ci.yml'\\)\\); print\\(' matrix:', d['jobs']['lint-and-test']['strategy']['matrix']['python-version']\\)\")",
+      "Bash(git config *)",
+      "Bash(echo \"name : $\\(git config user.name\\)\")",
+      "Bash(echo \"email: $\\(git config user.email\\)\")",
+      "Bash(git rebase *)",
+      "Bash(git fetch *)"
+    ]
+  }
+}

xtalate-0.1.0.dev0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.11 is the supported floor (catches use of newer syntax); 3.13 is the
+        # local dev interpreter (DECISIONS.md D11) — testing both keeps dev and CI
+        # from drifting.
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff (lint)
+        run: ruff check .
+
+      - name: Ruff (format)
+        run: ruff format --check .
+
+      - name: Mypy
+        run: mypy
+
+      - name: Import-graph lint (P2)
+        run: lint-imports
+
+      - name: Pytest
+        run: pytest

xtalate-0.1.0.dev0/.gitignore

@@ -0,0 +1,230 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+#MacOS
+.DS_Store
+
+# Secrets (CLAUDE.md "Never commit secrets" / DECISIONS.md) — defensive, ahead of need:
+# no credentials exist in the v0.1 codebase yet, but these patterns are excluded before
+# the v0.5 Service layer (DB, object storage, hosted-instance API keys) makes them real.
+*.pem
+*.key
+credentials.json
+secrets.*
+!secrets.*.example

xtalate-0.1.0.dev0/.import_linter_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by Grimp.
+*

xtalate-0.1.0.dev0/.import_linter_cache/711309a5eafe379c50451bc7ebdb0a6d9c6d28e6.data.json

@@ -0,0 +1 @@
+{"xtalate.parsers":[["xtalate.parsers.extxyz",14,"from xtalate.parsers.extxyz import ExtxyzParser"],["xtalate.sdk",17,"from xtalate.sdk import ParserPlugin"],["xtalate.parsers.poscar",15,"from xtalate.parsers.poscar import PoscarParser, make_contcar_parser, make_poscar_parser"],["xtalate.parsers.xyz",16,"from xtalate.parsers.xyz import XyzParser"]],"xtalate.parsers._common":[["xtalate.schema",15,"from xtalate.schema import ConversionRecord, Provenance"],["xtalate",14,"from xtalate import __version__"]],"xtalate.recovery.scenarios":[],"xtalate.recovery":[["xtalate.recovery.engine",15,"from xtalate.recovery.engine import ("],["xtalate.recovery.scenarios",23,"from xtalate.recovery.scenarios import ("]],"xtalate.exporters.poscar":[["xtalate.schema",21,"from xtalate.schema import CanonicalObject"],["xtalate.sdk",22,"from xtalate.sdk import ("]],"xtalate.validation":[["xtalate.validation.engine",13,"from xtalate.validation.engine import ConversionReportView, ValidationEngine"],["xtalate.validation.report",14,"from xtalate.validation.report import CheckResult, ValidationReport"],["xtalate.validation.tolerance",16,"from xtalate.validation.tolerance import ToleranceProfile"],["xtalate.validation.rethreshold",15,"from xtalate.validation.rethreshold import rethreshold"]],"xtalate.validation.tolerance":[],"xtalate.discovery.sniffer":[["xtalate.capabilities",26,"from xtalate.capabilities import Registry"]],"xtalate.schema.presence":[["xtalate.schema.models",30,"from xtalate.schema.models import CanonicalObject, Frame"]],"xtalate.capabilities":[["xtalate.capabilities.registry",9,"from xtalate.capabilities.registry import ("]],"xtalate.discovery.engine":[["xtalate.sdk",25,"from xtalate.sdk import CapabilityLevel, ParseError, ParseIssue"],["xtalate.capabilities",21,"from xtalate.capabilities import Registry"],["xtalate.schema",24,"from xtalate.schema import CanonicalObject"],["xtalate.discovery.sniffer",23,"from xtalate.discovery.sniffer import Sniffer, SniffResult"],["xtalate.discovery.report",22,"from xtalate.discovery.report import DiscoveryReport, FieldPresenceEntry"]],"xtalate":[],"xtalate.schema":[["xtalate.schema.models",7,"from xtalate.schema.models import ("],["xtalate.schema.presence",22,"from xtalate.schema.presence import PathPresence, PresenceMap"]],"xtalate.exporters":[["xtalate.exporters.poscar",14,"from xtalate.exporters.poscar import ("],["xtalate.exporters.extxyz",13,"from xtalate.exporters.extxyz import ExtxyzExporter"],["xtalate.exporters.xyz",19,"from xtalate.exporters.xyz import XyzExporter"],["xtalate.sdk",20,"from xtalate.sdk import ExporterPlugin"]],"xtalate.schema.arrays":[],"xtalate.conversion.report":[],"xtalate.sdk":[["xtalate.sdk.plugins",15,"from xtalate.sdk.plugins import ExporterPlugin, ParserPlugin"],["xtalate.sdk.results",16,"from xtalate.sdk.results import ParseError, ParseIssue, ParseResult"],["xtalate.sdk.capabilities",10,"from xtalate.sdk.capabilities import ("]],"xtalate.parsers.poscar":[["xtalate.schema",26,"from xtalate.schema import ("],["xtalate.parsers._common",25,"from xtalate.parsers._common import build_provenance"],["xtalate.schema.elements",36,"from xtalate.schema.elements import is_valid_symbol"],["xtalate.sdk",37,"from xtalate.sdk import ("]],"xtalate.validation.report":[["xtalate.sdk",15,"from xtalate.sdk import ParseIssue"]],"xtalate.cli.render":[["xtalate.discovery.report",12,"from xtalate.discovery.report import DiscoveryReport"],["xtalate.sdk",13,"from xtalate.sdk import CapabilityLevel, FormatCapabilities"],["xtalate.conversion.report",11,"from xtalate.conversion.report import ConversionReport"],["xtalate.validation.report",14,"from xtalate.validation.report import ValidationReport"]],"xtalate.discovery.report":[["xtalate.sdk",22,"from xtalate.sdk import CapabilityLevel, ParseIssue"]],"xtalate.sdk.capabilities":[],"xtalate.schema.elements":[],"xtalate.discovery":[["xtalate.discovery.report",10,"from xtalate.discovery.report import DiscoveryReport, FieldPresenceEntry"],["xtalate.discovery.sniffer",11,"from xtalate.discovery.sniffer import ("],["xtalate.discovery.engine",9,"from xtalate.discovery.engine import DiscoveryEngine"]],"xtalate.validation.engine":[["xtalate.schema",32,"from xtalate.schema import CanonicalObject"],["xtalate.capabilities",31,"from xtalate.capabilities import Registry"],["xtalate.sdk",33,"from xtalate.sdk import ParseError, ParseIssue"],["xtalate.validation.tolerance",35,"from xtalate.validation.tolerance import ToleranceProfile"],["xtalate.validation.report",34,"from xtalate.validation.report import CheckResult, ValidationReport"]],"xtalate.cli.main":[["xtalate.discovery",32,"from xtalate.discovery import DiscoveryEngine"],["xtalate.capabilities",24,"from xtalate.capabilities import Registry"],["xtalate.sdk",34,"from xtalate.sdk import ParseError"],["xtalate.registry",33,"from xtalate.registry import default_registry"],["xtalate.validation.rethreshold",35,"from xtalate.validation import ("],["xtalate.discovery",253,"from xtalate.discovery import Sniffer"],["xtalate.sdk",273,"from xtalate.sdk import ParseIssue"],["xtalate.cli.render",25,"from xtalate.cli import render"],["xtalate.validation",35,"from xtalate.validation import ("],["xtalate",23,"from xtalate import __version__"],["xtalate.conversion",26,"from xtalate.conversion import ("]],"xtalate.sdk.plugins":[["xtalate.sdk.results",17,"from xtalate.sdk.results import ParseResult"],["xtalate.schema",15,"from xtalate.schema import CanonicalObject"],["xtalate.sdk.capabilities",16,"from xtalate.sdk.capabilities import FormatCapabilities"]],"xtalate.parsers.extxyz":[["xtalate.parsers._common",47,"from xtalate.parsers._common import build_provenance"],["xtalate.schema",48,"from xtalate.schema import ("],["xtalate.sdk",58,"from xtalate.sdk import ("]],"xtalate.registry":[["xtalate.parsers",18,"from xtalate.parsers import builtin_parsers"],["xtalate.capabilities",16,"from xtalate.capabilities import Registry"],["xtalate.exporters",17,"from xtalate.exporters import builtin_exporters"]],"xtalate.conversion.preflight":[["xtalate.recovery",28,"from xtalate.recovery import UnresolvedScenario"],["xtalate.capabilities",26,"from xtalate.capabilities import CapabilityMatrix"],["xtalate.sdk",30,"from xtalate.sdk import CapabilityLevel"],["xtalate.schema",29,"from xtalate.schema import CanonicalObject"],["xtalate.conversion.report",27,"from xtalate.conversion.report import PreservedEntry, RemovedEntry, ReportWarning"]],"xtalate.recovery.engine":[["xtalate.recovery.scenarios",28,"from xtalate.recovery.scenarios import ("],["xtalate.schema",33,"from xtalate.schema import AtomsBlock, CanonicalObject, Cell, Frame"]],"xtalate.sdk.results":[["xtalate.schema",15,"from xtalate.schema import CanonicalObject"]],"xtalate.exporters.xyz":[["xtalate.schema",16,"from xtalate.schema import CanonicalObject"],["xtalate.sdk",17,"from xtalate.sdk import ("]],"xtalate.schema.paths":[["xtalate.schema.models",19,"from xtalate.schema.models import ("]],"xtalate.capabilities.registry":[["xtalate.schema.paths",16,"from xtalate.schema.paths import expand_capability_path, is_valid_path"],["xtalate.sdk",17,"from xtalate.sdk import ("]],"xtalate.parsers.xyz":[["xtalate.schema",30,"from xtalate.schema import ("],["xtalate.sdk",38,"from xtalate.sdk import ("],["xtalate.parsers._common",29,"from xtalate.parsers._common import build_provenance"],["xtalate.schema.elements",37,"from xtalate.schema.elements import is_valid_symbol"]],"xtalate.exporters.extxyz":[["xtalate.schema",22,"from xtalate.schema import CanonicalObject, Frame"],["xtalate.sdk",23,"from xtalate.sdk import ("]],"xtalate.conversion.engine":[["xtalate.sdk",58,"from xtalate.sdk import ParseIssue"],["xtalate",36,"from xtalate import __version__"],["xtalate.validation",59,"from xtalate.validation import ToleranceProfile, ValidationEngine, ValidationReport"],["xtalate.conversion.preflight",38,"from xtalate.conversion.preflight import PreflightDiff, build_preflight"],["xtalate.recovery",45,"from xtalate.recovery import RecoveryEngine"],["xtalate.capabilities",37,"from xtalate.capabilities import Registry"],["xtalate.conversion.report",383,"from xtalate.conversion.report import ReportWarning"],["xtalate.conversion.report",39,"from xtalate.conversion.report import ("],["xtalate.schema",46,"from xtalate.schema import ("]],"xtalate.schema.models":[["xtalate.schema.arrays",26,"from xtalate.schema.arrays import ("],["xtalate.schema.presence",248,"from xtalate.schema.presence import compute_field_presence"],["xtalate.schema.elements",33,"from xtalate.schema.elements import atomic_number, is_valid_symbol"],["xtalate.schema.presence",24,"from xtalate.schema.presence import PresenceMap"]],"xtalate.validation.rethreshold":[["xtalate.validation.tolerance",21,"from xtalate.validation.tolerance import ToleranceProfile"],["xtalate.validation.report",20,"from xtalate.validation.report import CheckResult, ValidationReport"]],"xtalate.conversion":[["xtalate.conversion.preflight",18,"from xtalate.conversion.preflight import ("],["xtalate.conversion.engine",12,"from xtalate.conversion.engine import ("],["xtalate.recovery",31,"from xtalate.recovery import UnresolvedScenario"],["xtalate.conversion.report",23,"from xtalate.conversion.report import ("]],"xtalate.cli":[["xtalate.cli.main",9,"from xtalate.cli.main import main"]]}

xtalate-0.1.0.dev0/.import_linter_cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag automatically created by Grimp.
+# For information about cache directory tags see https://bford.info/cachedir/

xtalate-0.1.0.dev0/.import_linter_cache/xtalate.meta.json

@@ -0,0 +1 @@
+{"xtalate.schema.presence": 1783833043.4318962, "xtalate.schema.arrays": 1783528075.2865715, "xtalate.schema.elements": 1783528075.2868724, "xtalate.exporters.xyz": 1783833043.4248168, "xtalate.sdk.plugins": 1783833043.4329252, "xtalate": 1783833043.4171271, "xtalate.conversion": 1783833043.4197884, "xtalate.discovery": 1783833043.4215312, "xtalate.cli.render": 1783833043.4192166, "xtalate.discovery.report": 1783833043.4224696, "xtalate.validation": 1783833043.4333227, "xtalate.validation.report": 1783833043.4348226, "xtalate.recovery": 1783833043.428564, "xtalate.exporters.poscar": 1783833043.4242523, "xtalate.recovery.scenarios": 1783833043.4294102, "xtalate.conversion.preflight": 1783833043.4210417, "xtalate.conversion.report": 1783830156.67924, "xtalate.parsers.xyz": 1783833043.427966, "xtalate.sdk.results": 1783833043.4331102, "xtalate.validation.engine": 1783833043.4338317, "xtalate.sdk.capabilities": 1783833043.4327276, "xtalate.parsers._common": 1783833043.4252386, "xtalate.schema": 1783833043.4300969, "xtalate.sdk": 1783833043.4324012, "xtalate.exporters": 1783833043.4230797, "xtalate.validation.tolerance": 1783830156.685212, "xtalate.capabilities.registry": 1783833043.4178298, "xtalate.capabilities": 1783833043.4173203, "xtalate.cli": 1783833043.4184995, "xtalate.exporters.extxyz": 1783833043.423647, "xtalate.schema.paths": 1783833043.431377, "xtalate.registry": 1783833043.429924, "xtalate.parsers.extxyz": 1783833043.4258244, "xtalate.parsers": 1783833043.4250007, "xtalate.recovery.engine": 1783833043.428934, "xtalate.discovery.engine": 1783833043.4218535, "xtalate.conversion.engine": 1783833043.4202921, "xtalate.discovery.sniffer": 1783833043.4227653, "xtalate.parsers.poscar": 1783833043.4269419, "xtalate.cli.main": 1783833043.4189324, "xtalate.validation.rethreshold": 1783833043.435106, "xtalate.schema.models": 1783833043.4308712}

xtalate-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to Xtalate are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). The canonical schema version is
+tracked separately from the package version and reaches `1.0.0` only in the v1.0 release
+(`docs/MASTER_SPEC.md` Part 2 §5); v0.1 objects carry `schema_version = "0.1.0"`.
+
+## [0.1.0] — 2026-07-10
+
+First release: the complete pure-Python **library + CLI** core. It converts between four
+computational-chemistry formats while reporting — and independently re-validating — every
+byte of scientific information kept, dropped, or fabricated.
+
+### Added
+
+- **Canonical Data Model** (`xtalate.schema`) — the single internal schema every parser
+  writes and every exporter reads, with the normative absence convention (`None` = "never in
+  the source" vs a real zero) and an on-demand `field_presence()` introspection.
+- **Plugin SDK, Format Sniffer, and Capability Matrix** (`xtalate.sdk`,
+  `xtalate.discovery`, `xtalate.capabilities`) — stable parser/exporter contracts, a
+  generic confidence-scored sniffer, and a per-format, per-field read/write capability registry.
+- **Formats** (`xtalate.parsers`, `xtalate.exporters`) — read and write for plain **XYZ**,
+  **extended XYZ** (ASE-backed, with default-laundering), **POSCAR**, and **CONTCAR**, each with a
+  golden round-trip and error-fixture suite.
+- **Information Discovery Engine** (`xtalate.discovery`) — the ✓/✗ Discovery Report: a file's
+  canonical-field inventory annotated with the detected format's read capability.
+- **Conversion Engine** (`xtalate.conversion`) — the pre-flight capability diff, the
+  `write_plan` discipline (materialized as a filtered `canonical′`), the Conversion Report, and
+  the completeness invariant enforced as an always-on runtime assertion.
+- **Recovery Engine** (`xtalate.recovery`) — explicit, preset-only resolution of the
+  `frame_selection` and `missing_lattice` scenarios under the three-way hazard model; every
+  choice recorded as an Assumption, and a structured **refusal** when no choice is supplied.
+- **Validation Engine** (`xtalate.validation`) — the unconditional post-conversion re-parse
+  and nine-check diff (Part 5 §2) under named tolerance profiles (`default`/`strict`/`loose`),
+  plus stored-report re-thresholding.
+- **CLI** (`xtalate`) — `inspect`, `convert`, `validate`, and `capabilities`, with the
+  CI-native exit-code contract (`0`/`2`/`3`/`4`/`5`/`1`) and `--json` structured output.
+
+### Known limitations (v0.1 scope)
+
+- No web service, REST API, or UI (v0.5 / v0.6).
+- CIF, XDATCAR, and ASE `.traj` — the remaining Phase-1 formats — are not yet implemented (v0.2+).
+- Recovery is preset-only; tolerance profiles are the three named ones (custom tables are later
+  seams).
+
+[0.1.0]: https://github.com/jsong1218/Xtalate/releases/tag/v0.1.0

xtalate-0.1.0.dev0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use Xtalate in your research, please cite it as below."
+title: "Xtalate: an audit-first converter for computational-chemistry file formats"
+abstract: >-
+  Xtalate is a translation layer between computational-chemistry file formats that reports
+  exactly what each conversion keeps, loses, or fabricates, and independently re-validates the
+  result. All translation flows through a single canonical data model; loss is predicted before
+  conversion and verified after.
+type: software
+authors:
+  - family-names: Song
+    given-names: Jiayu
+version: 0.1.0
+date-released: 2026-07-10
+license: Apache-2.0
+repository-code: "https://github.com/jsong1218/Xtalate"
+keywords:
+  - computational chemistry
+  - file format conversion
+  - materials science
+  - data provenance
+  - VASP
+  - ASE

xtalate-0.1.0.dev0/CLAUDE.md

@@ -0,0 +1,145 @@
+# CLAUDE.md — Xtalate Project Context
+
+> Load this file at the start of every Claude Code / Claude chat session working on Xtalate. It is a compressed index of `docs/MASTER_SPEC.md` (the full constitution — a single edited document, *not* an assembly of standalone files; see the document-family section below). If anything here conflicts with a doc in `docs/`, **the doc wins** — this file is a map, not the territory. If a later-uploaded doc contradicts an earlier one, flag the discrepancy; do not silently pick one.
+
+> **Status (refreshed Revision 1.6, July 2026).** **v0.1 is feature-complete** (MASTER_SPEC Preface Revision 1.2 item 17): the full spine — parse → pre-flight → recovery → export → report → validation — plus the Information Discovery Engine and the `xtalate` CLI are implemented, tested, and shipped for the four v0.1 formats (XYZ, extXYZ, POSCAR, CONTCAR). The map below is now current against Revisions 1.3–1.6 and `docs/DECISIONS.md` D1–D33; the two sections previously flagged HISTORICAL (Repository Shape, Documentation Set) have been rewritten to the real state. Mission, principles (P1–P6), glossary, architecture, the absence convention, tech stack (a *destination*, not the v0.1 dependency set), and API conventions remain binding. For current status and build-time rationale, read the **Revision 1.2 addenda** in the MASTER_SPEC Preface (the M0–M6 landing notes) and the **D-log through D33**; per-version execution lives in `docs/IMPLEMENTATION_PLAN_v0.1.md`–`_v1.0.md`.
+
+## Mission
+
+> **Xtalate is the trusted translation layer between computational chemistry file formats — a converter that tells you exactly what it kept, what it lost, and why.**
+
+Guiding philosophy: **never silently lose scientific information.** Litmus test for any design decision: *if a user diffed the source and output files by hand, would anything surprise them that Xtalate didn't already tell them about?* If yes, the design is wrong.
+
+## Design Principles (P1–P6) — binding, referenced by ID in every doc
+
+| ID | Principle |
+|----|-----------|
+| **P1** | Every loss is reported, never assumed. "The user probably doesn't need X" is never a valid reason for silence. |
+| **P2** | No parser talks to another parser. All translation flows through one Canonical Model: `Native File → Canonical Object → Target Format`. No format-to-format shortcuts, ever. |
+| **P3** | Absence is information. The schema distinguishes "never present in the source" (`None`) from "present with value zero/empty." |
+| **P4** | Recover explicitly, never guess. Missing-but-required data is supplied only through an explicit Recovery Workflow, recorded as an Assumption. |
+| **P5** | Know the formats before converting. The Capability Matrix predicts preservation/loss *before* conversion; Validation verifies it *after*. |
+| **P6** | Extensibility over optimization. New formats/features attach at defined seams without core redesign; performance is reclaimed later behind stable interfaces. |
+
+One sentence to carry into every doc: **a conversion you can't audit is a conversion you can't trust.**
+
+## Binding Glossary (use these terms verbatim; never coin synonyms)
+
+| Term | Meaning |
+|---|---|
+| **Canonical Model / Canonical Object** | The single internal schema every parser writes to and every exporter reads from (defined in `02_Canonical_Data_Model.md`). |
+| **Parser** | Reads exactly one native format → produces a Canonical Object. Never writes files, never calls another parser, never defaults an absent field. |
+| **Exporter** | Reads a Canonical Object → writes exactly one native format. Never reads native files. |
+| **Capability Matrix** | Per-format, per-field data structure declaring what each format can/cannot express; drives loss prediction. |
+| **Information Discovery Engine** | Inspects an arbitrary file and reports what's present/absent (✓/✗ per canonical field) without converting it. |
+| **Recovery Engine / Recovery Workflow** | Offers explicit, user-chosen ways to supply data a target format requires but the source lacks; every choice becomes an Assumption. |
+| **Conversion Report** | Structured, machine-readable record of what a conversion kept, dropped, transformed, or assumed. |
+| **Validation Report** | Post-conversion re-parse-and-diff result against the original Canonical Object, within tolerance. |
+| **Discovery Report** | Output of the Information Discovery Engine. |
+| **Provenance** | Canonical Model's record of source software, parser version, and full conversion history (incl. all Assumptions). |
+| **Plugin SDK** | Stable interface for third-party parsers/exporters/analysis modules; first-party formats hold no privileged API. |
+| **Round-trip** | `Format A → Canonical → Format B → Canonical`, diffed within tolerance; primary strategy for catching silent bugs. |
+| **Phase 1 formats** | The seven formats: XYZ, extXYZ, CIF, POSCAR, CONTCAR, XDATCAR, ASE trajectory. (Under the roadmap ladder these do not all land in the "MVP": roadmap v0.2's MVP is four of them — XYZ, extXYZ, POSCAR, CONTCAR, the v0.1 set — and all seven complete at roadmap v0.4. Say "the seven Phase 1 formats," not "the seven MVP formats.") |
+
+## Architecture at a Glance
+
+Single spine, four advisory subsystems that guide but never bypass it:
+
+```
+Native File → Format Sniffer → Parser → Canonical Object → Exporter → Target Format
+                                            ↑        ↓
+                        Information Discovery   Capability Matrix
+                        Recovery Engine (explicit only) → Validation Engine
+```
+
+- **Format Sniffer** — identifies format + confidence, selects a parser.
+- **Parser layer** (one per format) — must not read another format or talk to another parser.
+- **Canonical Object** — the only thing that crosses the parser/exporter boundary.
+- **Capability Matrix** — tells the exporter what the target can hold *before* it writes.
+- **Recovery Engine** — fills required-but-missing fields only with explicit user consent, recorded as an Assumption.
+- **Validation Engine** — re-parses the output and diffs it against the source Canonical Object.
+- **API layer** (`backend/`, FastAPI) — thin; validates requests, manages jobs/storage; contains no scientific logic.
+- **Web UI** (`frontend/`, Next.js) — presents the workflow and renders reports faithfully; never re-implements conversion logic or hides losses.
+
+## Canonical Model — Absence Convention (P3), normative
+
+| State | Representation | Meaning |
+|---|---|---|
+| Absent | `None` | Source file did not contain this information at all. |
+| Present | Actual value (incl. zeros) | Source file contained it; the value is the value. |
+
+Parsers are forbidden from defaulting — no zero velocities, no identity lattice, no `energy = 0.0` invented to fill a gap. Schema categories: Geometry, Simulation Cell, Trajectory, Dynamics, Electronic Information, Simulation Metadata, Provenance, User Metadata. Modeled as pydantic v2-style; NumPy arrays in memory, nested JSON lists on the wire; internal coordinates and unit conventions are defined normatively in `02_Canonical_Data_Model.md` — treat field names there as final.
+
+## Tech Stack (rationale lives in `01_Architecture.md §4`)
+
+> These are destination choices for the versions that need them (Service in v0.5, Web UI in v0.6), not the v0.1 dependency set. v0.1 is a pure-Python library + CLI: pydantic + numpy, plus ASE once the extXYZ parser lands (the sole scientific dependency — pymatgen was rejected as a v0.1 dependency; see `docs/DECISIONS.md` D4, D7).
+
+| Layer | Choice |
+|---|---|
+| Frontend | Next.js + React + Tailwind |
+| Backend | FastAPI (Python — must be in-process with ASE/pymatgen) |
+| Scientific core | ASE + pymatgen |
+| Future visualization | Mol* (secondary goal, not MVP) |
+| Relational DB | PostgreSQL (JSONB for report bodies) |
+| Blob storage | S3-compatible object storage, lifecycle-expiring |
+| Job queue | RQ on Redis |
+
+## Repository Shape (current v0.1 layout)
+
+> The pre-implementation architecture review rejected a solo-maintainer monorepo of separately-packaged components as unnecessary overhead (`docs/ARCHITECTURE_REVIEW.md` §4.1; `docs/DECISIONS.md` D1). The shipped v0.1 layout is **one package** in a `src/` layout — no per-component `pyproject.toml`s. `frontend/`, `backend/`, and `plugins/` do not exist yet; they arrive with the versions that need them (Service at roadmap v0.5, Web UI at v0.6, entry-point plugin discovery at v0.3). `docs/MASTER_SPEC.md` Part 1 §5 is the authoritative tree.
+
+```
+src/xtalate/
+  schema/         Canonical Model; depends on nothing else in xtalate/  (a.k.a. "canonical-schema")
+  sdk/            stable parser/exporter base classes + capability models   (a.k.a. "plugin-sdk")
+  parsers/        one per format; depends only on schema + sdk
+  exporters/      one per format; depends only on schema + sdk
+  capabilities/   Capability Matrix: assembles + queries declarations       (a.k.a. "capability-matrix")
+  discovery/      Information Discovery Engine + Format Sniffer + Discovery Report
+  conversion/     Conversion Engine — orchestrates the above + Conversion Report
+  recovery/       Recovery Engine + workflows (preset-only in v0.1)
+  validation/     Validation Engine + Validation Report
+  cli/            thin argparse presenter: inspect / convert / validate / capabilities
+examples/         runnable end-to-end library + CLI samples
+tests/            golden/, roundtrip/, and per-subpackage suites
+docs/             the doc family this file indexes
+```
+
+Dependency direction is strict and acyclic — enforced physically by an `import-linter` `layers` contract (`pyproject.toml`), run with ruff + mypy --strict + pytest on every PR (`docs/DECISIONS.md` D5). This is what enforces **P2**. The descriptive names in parentheses (`canonical-schema`, `plugin-sdk`, `capability-matrix`) are the prose labels used across the spec; the tree gives the import-name mapping.
+
+## API Conventions (full spec in `06_API.md`)
+
+- All endpoints under `/v1/`. Path-prefix versioning; additive changes are non-breaking; new formats/scenarios are *values*, not new endpoints.
+- Long-running operations (`inspect`, `convert`, `validate`) are **async jobs**: submit → poll `/v1/jobs/{job_id}` → retrieve result.
+- Job states: `queued → running → completed | failed | cancelled`, plus `queued → failed` (dequeue-precondition failure, Revision 1.1) and `running → awaiting_recovery → running | expired`. An expired `awaiting_recovery` job resolves to a **refused** conversion, never a silently applied default.
+- **A refusal is not an HTTP error.** A conversion the engine declines is a completed job whose `ConversionReport.status == "refused"` — HTTP 200.
+- Single error envelope for all non-2xx responses: `{ error: { code, message, details, request_id, documentation_url } }`. Codes are stable machine strings (e.g. `UNKNOWN_FORMAT`, `PARSE_ERROR`, `VALIDATION_ACK_REQUIRED`, `JOB_ALREADY_TERMINAL`).
+- Response bodies embed the pydantic report models verbatim (`DiscoveryReport`, `ConversionReport`, `ValidationReport`) — no parallel DTOs.
+
+*(This describes the v0.5 Service layer's target contract; there is no API yet in v0.1.)*
+
+## Documentation Set
+
+> `docs/MASTER_SPEC.md` is edited directly as the single source of truth (Revision 1.2, Preface); the standalone `00`–`10` `.md` files named in older prose **never existed as separate committed files** — do not create or assume them. The Part numbering (`04 §3.3` = "Part 4 §3.3") survives only as a stable citation scheme inside the one document. The document family that actually exists:
+
+- **`docs/MASTER_SPEC.md`** — the constitution (Parts 0–10 + Appendices; Preface revision log runs Revisions 1.1–1.6). Start here; use its Table of Contents.
+- **`docs/DECISIONS.md`** — build-time decisions log, **D1–D33**, each with a rejected alternative and a standing-rules note at the top.
+- **`docs/ARCHITECTURE_REVIEW.md`** — the accepted pre-implementation review (its acceptance is MASTER_SPEC Revision 1.2).
+- **`docs/Incremental_Roadmap_v1.0.md`** — the solo-developer version ladder (v0.1–v0.7); carries a Revision 1.6 staleness banner over its execution detail, ladder still binding.
+- **`docs/IMPLEMENTATION_PLAN_v0.1.md` … `_v1.0.md`** — per-version execution plans, milestones **M0–M38**, each superseding the roadmap's execution prose for its version.
+- **`docs/DOCS_CONSISTENCY_REVIEW_2026-07.md`** — the post-v0.1 corpus consistency review (findings C1–C11) this refresh implements.
+
+> Not committed to this repo (external, historical): `Xtalate_Doc_Prompts.md` — the prompt set that generated the original drafts; superseded by the single-source-of-truth model, do not run it or create the standalone files.
+
+## Working Rules for This Project
+
+- **Terminology is binding.** Reuse exact field names, endpoint paths, report field names, and component names already established. If a name seems wrong, say so explicitly and explain why — never rename silently.
+- **Write for an isolated reader.** Every doc must stand alone for a contributor or a planning agent who has not read the master prompt directly, while staying consistent with the rest of `docs/`.
+- **Justify nontrivial decisions.** Name at least one reasonable rejected alternative for each nontrivial architectural or design choice.
+- **No silent data loss, ever — including in the docs themselves.** Any design that could cause silent loss must be called out explicitly, not glossed over.
+- **MVP discipline.** Favor maintainability, correctness, and extensibility over convenience; don't overengineer Phase 1, but never foreclose Secondary Goals — name the extensibility seam they'd attach to.
+- **Scope discipline.** Produce only the file(s) a given prompt asks for. Do not pad a doc with content that belongs in a different doc file.
+- **Format.** Professional Markdown; Mermaid for all diagrams (GitHub-renderable); directory trees where relevant; no marketing language — this is engineering documentation, not a pitch.
+- **No AI attribution in commits.** No `Co-Authored-By` AI trailer, no "Generated with …" line, and no AI listed as author or contributor in commit metadata, `CITATION.cff`, or release notes — the human maintainer is the author of record on every commit an agent creates or assists with. (`docs/MASTER_SPEC.md` Preface; `docs/DECISIONS.md` D10.)
+- **Never commit secrets.** No API keys, tokens, database credentials, or other secrets are ever committed to this repository, in code, config, fixtures, or commit messages — not even temporarily, not even in a since-reverted commit (git history is not a safe place to "fix it later"). Secrets are supplied only via environment variables or an untracked local file (`.env`, already gitignored) and referenced by name in code, never inlined. Before staging or committing, check `git status`/`git diff` for anything that looks like a credential — including in filenames that look innocuous — and stop to ask if unsure. If a secret is ever accidentally committed, the fix is rotation (invalidate the leaked credential) *and* history rewrite, not just a follow-up commit that deletes it. There are no secrets in the v0.1 codebase (pure-Python library + CLI, no network calls, no credentials); this rule exists ahead of need because v0.5 (Service layer: database, object storage, hosted-instance API keys) is exactly where a leak would first become possible, and the discipline should already be established by then.
+