servatus 0.0.1__tar.gz

servatus-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - run: uv run vulture
+      - run: uv build
+      - run: uv run --isolated --no-project --with dist/*.whl python -c "import servatus"

servatus-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

servatus-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+*.egg-info/

servatus-0.0.1/AGENTS.md

@@ -0,0 +1,10 @@
+# Agent guidance
+
+Servatus favors small, deep interfaces and ordinary typed Python. Keep application meaning outside
+the package, reject unsafe filesystem behavior, and prefer clean breaks over compatibility layers.
+
+Use synthetic temporary directories for tests. Never contact SSH, Slurm, Apptainer, external
+storage, or an application's real outputs from the test suite.
+
+Run pytest, Ruff, Pyright, Vulture, package builds, and an installed-artifact smoke before handing
+off a change.

servatus-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Servatus keeps its public surface deliberately small. Changes should solve a demonstrated lifecycle
+problem without importing application schemas, workflow topology, or backend plugin machinery.
+
+Set up and verify the repository with:
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run vulture
+uv build
+```
+
+Tests must use synthetic temporary directories. Pull requests must not depend on a live scheduler,
+cluster, container runtime, or external data store.

servatus-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edoardo Galli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

servatus-0.0.1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: servatus
+Version: 0.0.1
+Summary: Run resumable work through Slurm and atomically publish validated outputs.
+Project-URL: Repository, https://github.com/edoski/servatus
+Project-URL: Issues, https://github.com/edoski/servatus/issues
+Author: Edoardo Galli
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Servatus
+
+Run resumable work through Slurm and atomically publish validated outputs.
+
+Servatus 0.0.1 is a publication-only alpha. It provides a small Python interface for keeping
+private resumable work and exposing an application-built directory atomically. Slurm campaigns
+arrive in a later release.
+
+```sh
+pip install servatus
+```
+
+## Publication
+
+Use `publish` when failed work is disposable:
+
+```python
+from pathlib import Path
+
+from servatus import Draft, publish
+
+
+def build(draft: Draft) -> None:
+    (draft.path / "result.json").write_text('{"status":"complete"}\n')
+
+
+publication = publish(Path("outputs/run-1"), build)
+```
+
+Use `Workspace` when a worker must retain private checkpoints across restarts:
+
+```python
+from servatus import Draft, Workspace
+
+destination = Path("outputs/model-1")
+with Workspace(destination, identity=b"model request bytes") as workspace:
+    checkpoint = workspace.path / "last.ckpt"
+    # The application creates or resumes its own checkpoint here.
+
+    def assemble(draft: Draft) -> None:
+        draft.link(checkpoint, "last.ckpt")
+        # Perform application validation before returning.
+
+    publication = workspace.publish(assemble)
+```
+
+`Workspace` binds its stable hidden state to the SHA-256 digest of the opaque identity and holds a
+nonblocking writer lock. `Draft.link` only hard-links regular files into a safe relative path. The
+application must not mutate a linked source inode after `Draft.link()` returns and before
+publication completes. It owns file contents, validation, schemas, and completion meaning.
+
+## Guarantees
+
+- A destination is absent or one complete directory; it is never overwritten.
+- Work, hard-link sources, stages, and destination must share a filesystem.
+- Files and directories are synced before a kernel-exclusive commit; the destination parent is
+  synced afterward.
+- Builder failures expose no destination. Resumable work remains available, while disposable
+  stages are removed.
+- Successful workspace publication removes private state. A cleanup failure returns
+  `Publication(cleanup_pending=True)` without misreporting the committed destination as failed.
+- Symlinks, special files, escaping link paths, path substitution, and unsupported exclusive-rename
+  primitives fail closed.
+
+Servatus supports POSIX filesystems on Linux and macOS. Hardware durability still depends on the
+filesystem and mount. It is not a security boundary against another process that can arbitrarily
+modify the same parent directory.
+
+## Non-goals in 0.0.1
+
+Servatus does not interpret checkpoints or ML artifacts, decide when work is valid, model workflow
+graphs, migrate old outputs, copy across filesystems, overwrite destinations, or provide scheduler
+execution. It has no plugins, callbacks beyond the one build seam, runtime dependencies, daemon,
+database, or global run store.
+
+The public API is `Draft`, `Workspace`, `Publication`, `publish`, and the compact errors exported by
+`servatus`. See [the context glossary](docs/CONTEXT.md) and [architecture decisions](docs/adr/README.md)
+for the ownership boundary.

servatus-0.0.1/README.md

@@ -0,0 +1,78 @@
+# Servatus
+
+Run resumable work through Slurm and atomically publish validated outputs.
+
+Servatus 0.0.1 is a publication-only alpha. It provides a small Python interface for keeping
+private resumable work and exposing an application-built directory atomically. Slurm campaigns
+arrive in a later release.
+
+```sh
+pip install servatus
+```
+
+## Publication
+
+Use `publish` when failed work is disposable:
+
+```python
+from pathlib import Path
+
+from servatus import Draft, publish
+
+
+def build(draft: Draft) -> None:
+    (draft.path / "result.json").write_text('{"status":"complete"}\n')
+
+
+publication = publish(Path("outputs/run-1"), build)
+```
+
+Use `Workspace` when a worker must retain private checkpoints across restarts:
+
+```python
+from servatus import Draft, Workspace
+
+destination = Path("outputs/model-1")
+with Workspace(destination, identity=b"model request bytes") as workspace:
+    checkpoint = workspace.path / "last.ckpt"
+    # The application creates or resumes its own checkpoint here.
+
+    def assemble(draft: Draft) -> None:
+        draft.link(checkpoint, "last.ckpt")
+        # Perform application validation before returning.
+
+    publication = workspace.publish(assemble)
+```
+
+`Workspace` binds its stable hidden state to the SHA-256 digest of the opaque identity and holds a
+nonblocking writer lock. `Draft.link` only hard-links regular files into a safe relative path. The
+application must not mutate a linked source inode after `Draft.link()` returns and before
+publication completes. It owns file contents, validation, schemas, and completion meaning.
+
+## Guarantees
+
+- A destination is absent or one complete directory; it is never overwritten.
+- Work, hard-link sources, stages, and destination must share a filesystem.
+- Files and directories are synced before a kernel-exclusive commit; the destination parent is
+  synced afterward.
+- Builder failures expose no destination. Resumable work remains available, while disposable
+  stages are removed.
+- Successful workspace publication removes private state. A cleanup failure returns
+  `Publication(cleanup_pending=True)` without misreporting the committed destination as failed.
+- Symlinks, special files, escaping link paths, path substitution, and unsupported exclusive-rename
+  primitives fail closed.
+
+Servatus supports POSIX filesystems on Linux and macOS. Hardware durability still depends on the
+filesystem and mount. It is not a security boundary against another process that can arbitrarily
+modify the same parent directory.
+
+## Non-goals in 0.0.1
+
+Servatus does not interpret checkpoints or ML artifacts, decide when work is valid, model workflow
+graphs, migrate old outputs, copy across filesystems, overwrite destinations, or provide scheduler
+execution. It has no plugins, callbacks beyond the one build seam, runtime dependencies, daemon,
+database, or global run store.
+
+The public API is `Draft`, `Workspace`, `Publication`, `publish`, and the compact errors exported by
+`servatus`. See [the context glossary](docs/CONTEXT.md) and [architecture decisions](docs/adr/README.md)
+for the ownership boundary.

servatus-0.0.1/SECURITY.md

@@ -0,0 +1,11 @@
+# Security policy
+
+Please report vulnerabilities privately through GitHub's security-advisory form for this
+repository. Do not include sensitive paths, credentials, or research data in a public issue.
+
+Only the latest released version receives security fixes.
+
+Servatus is an unprivileged user library, not an authorization, sandboxing, tenant-isolation, or
+cluster-policy layer. Its publication transaction protects against accidental partial visibility,
+overwrites, and ordinary lifecycle races. Callers remain responsible for directory permissions,
+trusted builders, application validation, filesystem guarantees, and scheduler policy.

servatus-0.0.1/docs/CONTEXT.md

@@ -0,0 +1,13 @@
+# Servatus context
+
+Servatus uses a small generic vocabulary:
+
+- **Destination:** the application-owned canonical path. It is immutable once published.
+- **Workspace:** stable, identity-bound private state retained when resumable work fails.
+- **Identity:** opaque application bytes whose digest binds a workspace to one logical request.
+- **Draft:** one unique, disposable directory assembled before publication.
+- **Publication:** the committed destination plus whether private cleanup remains pending.
+- **Builder:** the application callback that writes and validates a draft before returning.
+
+Servatus owns lifecycle mechanics, not application meaning. Checkpoints, manifests, schemas,
+validation rules, task topology, and scientific completion remain with the calling project.

servatus-0.0.1/docs/adr/0001-opaque-application-seam.md

@@ -0,0 +1,10 @@
+# ADR 0001: Keep application meaning opaque
+
+Status: accepted
+
+Servatus accepts opaque identity bytes and one application-owned builder callback. The callback
+writes the exact destination tree and performs domain validation before returning.
+
+Servatus does not receive artifact schemas, validators, checkpoint formats, completion enums, or
+workflow topology. This keeps the lifecycle reusable without becoming an ML framework or moving
+scientific authority away from the calling project.

servatus-0.0.1/docs/adr/0002-posix-workspace-publication.md

@@ -0,0 +1,15 @@
+# ADR 0002: Publish through a durable POSIX transaction
+
+Status: accepted
+
+Servatus builds in a unique destination-adjacent stage, rejects unsafe entries, recursively syncs
+content, and atomically renames the directory into an absent destination with the platform's
+no-replace primitive. It then syncs the destination parent.
+
+Linux uses `renameat2(RENAME_NOREPLACE)` and macOS uses descriptor-relative
+`renameatx_np(RENAME_EXCL)`. Unsupported systems and filesystems fail closed. Work, stages, link
+sources, and destinations must share one filesystem; Servatus never weakens the contract with a
+copy or check-then-rename fallback.
+
+An identity-bound workspace is retained after build failure and removed only after a committed,
+parent-synced publication. Cleanup failure is reported separately from publication success.

servatus-0.0.1/docs/adr/README.md

@@ -0,0 +1,4 @@
+# Architecture decisions
+
+- [0001: Keep application meaning opaque](0001-opaque-application-seam.md)
+- [0002: Publish through a durable POSIX transaction](0002-posix-workspace-publication.md)

servatus-0.0.1/docs/agents/issue-tracker.md

@@ -0,0 +1,5 @@
+# Issue tracker
+
+GitHub Issues is the repository's issue tracker. Keep reports scoped to a reproducible Servatus
+contract or implementation problem. Application-specific workflow and artifact questions belong in
+the calling project's tracker.

servatus-0.0.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "servatus"
+version = "0.0.1"
+description = "Run resumable work through Slurm and atomically publish validated outputs."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Edoardo Galli" }]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/edoski/servatus"
+Issues = "https://github.com/edoski/servatus/issues"
+
+[dependency-groups]
+dev = [
+  "pyright>=1.1.404",
+  "pytest>=8.4",
+  "ruff>=0.12",
+  "vulture>=2.14",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/servatus"]
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "SIM", "UP"]
+
+[tool.vulture]
+min_confidence = 90
+paths = ["src"]

servatus-0.0.1/src/servatus/__init__.py

@@ -0,0 +1,26 @@
+from ._errors import (
+    CrossDevicePublication,
+    DestinationExists,
+    PublicationError,
+    ServatusError,
+    UnsafePublication,
+    UnsupportedPlatform,
+    WorkConflict,
+    WorkspaceBusy,
+)
+from ._workspace import Draft, Publication, Workspace, publish
+
+__all__ = [
+    "CrossDevicePublication",
+    "DestinationExists",
+    "Draft",
+    "Publication",
+    "PublicationError",
+    "ServatusError",
+    "UnsafePublication",
+    "UnsupportedPlatform",
+    "WorkConflict",
+    "Workspace",
+    "WorkspaceBusy",
+    "publish",
+]

servatus-0.0.1/src/servatus/_errors.py

@@ -0,0 +1,30 @@
+class ServatusError(Exception):
+    """Base class for Servatus contract failures."""
+
+
+class PublicationError(ServatusError):
+    """A draft could not be safely published."""
+
+
+class DestinationExists(PublicationError):
+    """The requested destination or draft entry already exists."""
+
+
+class CrossDevicePublication(PublicationError):
+    """Publication would cross a filesystem boundary."""
+
+
+class UnsafePublication(PublicationError):
+    """A path or filesystem entry violates the publication contract."""
+
+
+class UnsupportedPlatform(PublicationError):
+    """The platform cannot provide an atomic no-replace commit."""
+
+
+class WorkConflict(ServatusError):
+    """Existing private work is bound to another identity."""
+
+
+class WorkspaceBusy(ServatusError):
+    """Another writer currently owns the workspace."""