sheaffoundry 0.1.0a1__tar.gz

sheaffoundry-0.1.0a1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/

sheaffoundry-0.1.0a1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: sheaffoundry
+Version: 0.1.0a1
+Summary: Deterministic assembly plans for named inputs and reproducible build receipts.
+Project-URL: Repository, https://github.com/SheafLab/sheaffoundry-python
+Author: SheafLab
+License: MIT
+Keywords: assembly,plans,provenance,reproducibility,sheaflab
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# sheaffoundry
+
+`sheaffoundry` models a small, reviewable assembly plan. A plan names its
+inputs, orders assembly steps, and emits a deterministic receipt suitable for
+logs, test fixtures, or provenance records.
+
+```python
+from sheaffoundry import AssemblyPlan, Input, Step
+
+plan = AssemblyPlan(
+    "preview-image",
+    inputs=(Input("source", "sha256:abc"), Input("palette", "v3")),
+    steps=(Step("decode"), Step("render", needs=("decode",))),
+)
+
+receipt = plan.receipt()
+assert receipt.step_order == ("decode", "render")
+```
+
+Steps form a directed acyclic graph. The package validates missing dependencies
+and cycles, then uses lexical tie-breaking to produce a stable execution order.
+There are no runtime dependencies.

sheaffoundry-0.1.0a1/README.md

@@ -0,0 +1,22 @@
+# sheaffoundry
+
+`sheaffoundry` models a small, reviewable assembly plan. A plan names its
+inputs, orders assembly steps, and emits a deterministic receipt suitable for
+logs, test fixtures, or provenance records.
+
+```python
+from sheaffoundry import AssemblyPlan, Input, Step
+
+plan = AssemblyPlan(
+    "preview-image",
+    inputs=(Input("source", "sha256:abc"), Input("palette", "v3")),
+    steps=(Step("decode"), Step("render", needs=("decode",))),
+)
+
+receipt = plan.receipt()
+assert receipt.step_order == ("decode", "render")
+```
+
+Steps form a directed acyclic graph. The package validates missing dependencies
+and cycles, then uses lexical tie-breaking to produce a stable execution order.
+There are no runtime dependencies.

sheaffoundry-0.1.0a1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sheaffoundry"
+version = "0.1.0a1"
+description = "Deterministic assembly plans for named inputs and reproducible build receipts."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SheafLab" }]
+keywords = ["assembly", "provenance", "plans", "reproducibility", "sheaflab"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Repository = "https://github.com/SheafLab/sheaffoundry-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sheaffoundry"]

sheaffoundry-0.1.0a1/src/sheaffoundry/__init__.py

@@ -0,0 +1,4 @@
+from .plan import AssemblyPlan, Input, Receipt, Step
+
+__all__ = ["AssemblyPlan", "Input", "Receipt", "Step"]
+__version__ = "0.1.0a1"

sheaffoundry-0.1.0a1/src/sheaffoundry/plan.py

@@ -0,0 +1,74 @@
+"""Dependency-checked, deterministic assembly plans."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Input:
+    name: str
+    reference: str
+
+    def __post_init__(self) -> None:
+        if not self.name.strip() or not self.reference.strip():
+            raise ValueError("inputs require non-empty names and references")
+
+
+@dataclass(frozen=True, slots=True)
+class Step:
+    name: str
+    needs: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError("steps require a non-empty name")
+
+
+@dataclass(frozen=True, slots=True)
+class Receipt:
+    plan: str
+    inputs: tuple[Input, ...]
+    step_order: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class AssemblyPlan:
+    name: str
+    inputs: tuple[Input, ...] = ()
+    steps: tuple[Step, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError("plans require a non-empty name")
+        if len({item.name for item in self.inputs}) != len(self.inputs):
+            raise ValueError("input names must be unique")
+        if len({step.name for step in self.steps}) != len(self.steps):
+            raise ValueError("step names must be unique")
+        known = {step.name for step in self.steps}
+        missing = sorted({dependency for step in self.steps for dependency in step.needs} - known)
+        if missing:
+            raise ValueError(f"unknown step dependencies: {', '.join(missing)}")
+        self.execution_order()
+
+    def execution_order(self) -> tuple[str, ...]:
+        """Topologically order steps with deterministic tie-breaking."""
+
+        waiting = {step.name: set(step.needs) for step in self.steps}
+        ordered: list[str] = []
+        while waiting:
+            ready = sorted(name for name, needs in waiting.items() if not needs)
+            if not ready:
+                raise ValueError("step dependencies contain a cycle")
+            for name in ready:
+                del waiting[name]
+                ordered.append(name)
+            completed = set(ready)
+            for needs in waiting.values():
+                needs.difference_update(completed)
+        return tuple(ordered)
+
+    def receipt(self) -> Receipt:
+        """Capture the plan's stable inputs and execution order."""
+
+        return Receipt(self.name, tuple(sorted(self.inputs, key=lambda item: item.name)), self.execution_order())

sheaffoundry-0.1.0a1/tests/test_plan.py

@@ -0,0 +1,17 @@
+import unittest
+
+from sheaffoundry import AssemblyPlan, Input, Step
+
+
+class AssemblyPlanTests(unittest.TestCase):
+    def test_execution_order_is_stable(self) -> None:
+        plan = AssemblyPlan("demo", steps=(Step("publish", ("build",)), Step("build"), Step("audit")))
+        self.assertEqual(plan.execution_order(), ("audit", "build", "publish"))
+
+    def test_receipt_sorts_inputs(self) -> None:
+        plan = AssemblyPlan("demo", inputs=(Input("z", "3"), Input("a", "1")))
+        self.assertEqual(tuple(item.name for item in plan.receipt().inputs), ("a", "z"))
+
+    def test_cycle_is_rejected(self) -> None:
+        with self.assertRaises(ValueError):
+            AssemblyPlan("cycle", steps=(Step("a", ("b",)), Step("b", ("a",))))