moveset 0.1.0__tar.gz

moveset-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ella Inng
+
+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.

moveset-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: moveset
+Version: 0.1.0
+Summary: Explicit linear composition of selected Python capabilities.
+Author: ellainng
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: hidden-moves>=0.1.0
+Requires-Dist: func-seq>=0.1.0 ; python_full_version >= '3.14' and extra == 'sequence'
+Requires-Python: >=3.11
+Project-URL: Source, https://github.com/wispsy/moveset
+Project-URL: Issues, https://github.com/wispsy/moveset/issues
+Project-URL: Project, https://github.com/orgs/wispsy/projects/23
+Provides-Extra: sequence
+Description-Content-Type: text/markdown
+
+# Moveset
+
+Explicit linear composition of selected Python capabilities. Python 3.11+.
+
+```python
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from moveset import Input, Pipeline, Ref, Step
+
+def normalize(text: str) -> str:
+    return " ".join(text.lower().split())
+
+moves = Moves()
+moves.learn(normalize)
+selected = CapabilityCatalog(moves, ["normalize"])
+definition = Pipeline("example", version="1", steps=(
+    Step("clean", "normalize", {"text": Input("text")}),
+), outputs={"text": Ref("clean")})
+bound = definition.bind(selected, catalog_version="text-v1")
+assert bound.run({"text": " Hello WORLD "}).outputs == {"text": "hello world"}
+```
+
+Definitions snapshot nested arguments and outputs. `Input("payload")["key"][0]`
+selects run data; `Ref("clean")` selects an earlier result. Mappings are explicit:
+scalar results are never automatically wrapped in objects. Binding validates
+selected capability names and known argument shapes. Run preflight validates all
+known inputs before effects; dynamic result paths and values are checked before
+the dependent call. Hidden Moves owns its documented schema subset and callable
+binding. No provider is activated by creating or executing a pipeline.
+
+`arun(inputs)` awaits mixed sync/async steps in order. `run` rejects declared async
+steps before executing anything. Cancellation propagates; ordinary runs start
+fresh. Results are caller-owned finite JSON snapshots, bounded to 1 MiB with depth
+32; definitions have at most 256 steps. StepError identifies the step/capability
+and retains the original cause. There is no retry, persistence or concurrency in
+the core.
+
+The bound fingerprint includes mappings, schemas, async flags and catalog version.
+Change `catalog_version` when callable behavior, resources, defaults or configuration
+change; this is not source authentication. The optional lifecycle adapter belongs
+in the `sequence` profile and delegates durable execution to func_seq.
+
+This source development profile pins Hidden Moves to an immutable revision. It is
+independently built and versioned; release requirements and publication are tracked
+separately in the [Wispsy Composition Project](https://github.com/orgs/wispsy/projects/23).
+
+Build with `uv build --out-dir dist`; `python scripts/qualify.py dist` installs the
+wheel and source archive outside the checkout and runs the contract tests. CI
+qualifies Python 3.11 on Linux/Windows and Python 3.14 on Linux/macOS/Windows.

moveset-0.1.0/README.md

@@ -0,0 +1,49 @@
+# Moveset
+
+Explicit linear composition of selected Python capabilities. Python 3.11+.
+
+```python
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from moveset import Input, Pipeline, Ref, Step
+
+def normalize(text: str) -> str:
+    return " ".join(text.lower().split())
+
+moves = Moves()
+moves.learn(normalize)
+selected = CapabilityCatalog(moves, ["normalize"])
+definition = Pipeline("example", version="1", steps=(
+    Step("clean", "normalize", {"text": Input("text")}),
+), outputs={"text": Ref("clean")})
+bound = definition.bind(selected, catalog_version="text-v1")
+assert bound.run({"text": " Hello WORLD "}).outputs == {"text": "hello world"}
+```
+
+Definitions snapshot nested arguments and outputs. `Input("payload")["key"][0]`
+selects run data; `Ref("clean")` selects an earlier result. Mappings are explicit:
+scalar results are never automatically wrapped in objects. Binding validates
+selected capability names and known argument shapes. Run preflight validates all
+known inputs before effects; dynamic result paths and values are checked before
+the dependent call. Hidden Moves owns its documented schema subset and callable
+binding. No provider is activated by creating or executing a pipeline.
+
+`arun(inputs)` awaits mixed sync/async steps in order. `run` rejects declared async
+steps before executing anything. Cancellation propagates; ordinary runs start
+fresh. Results are caller-owned finite JSON snapshots, bounded to 1 MiB with depth
+32; definitions have at most 256 steps. StepError identifies the step/capability
+and retains the original cause. There is no retry, persistence or concurrency in
+the core.
+
+The bound fingerprint includes mappings, schemas, async flags and catalog version.
+Change `catalog_version` when callable behavior, resources, defaults or configuration
+change; this is not source authentication. The optional lifecycle adapter belongs
+in the `sequence` profile and delegates durable execution to func_seq.
+
+This source development profile pins Hidden Moves to an immutable revision. It is
+independently built and versioned; release requirements and publication are tracked
+separately in the [Wispsy Composition Project](https://github.com/orgs/wispsy/projects/23).
+
+Build with `uv build --out-dir dist`; `python scripts/qualify.py dist` installs the
+wheel and source archive outside the checkout and runs the contract tests. CI
+qualifies Python 3.11 on Linux/Windows and Python 3.14 on Linux/macOS/Windows.

moveset-0.1.0/docs/lifecycle.md

@@ -0,0 +1,26 @@
+# Optional durable execution
+
+Install the `sequence` profile on Python 3.14+. The base import does not load
+func_seq and remains usable on Python 3.11+.
+
+```python
+from moveset.sequence import compile_script
+script = compile_script(bound, inputs)
+progress = script.run(checkpoint="progress.json", pace="function")
+progress = script.run(checkpoint="progress.json")
+if progress.status == "completed":
+    result = bound.finish(inputs, progress.results)
+```
+
+`compile_script(..., asynchronous=True)` supports `await script.arun()` for mixed
+sync/async or sync-returned-awaitable operations. Execution mode is part of identity.
+All mappings translate to func_seq values/references with the original step IDs.
+The Script version hashes the bound fingerprint, run inputs and execution mode.
+Mapping, schema, catalog version, output, input or mode changes reject old progress.
+Callable/environment changes require the host to change catalog_version.
+
+Use func_seq.Control, observers, pace, retry, restart and checkpoint directly.
+Cooperative pause occurs at boundaries; cancellation propagates through arun.
+Cancellation or failure may follow an effect: an uncertain action requires explicit
+retry=True or restart=True. Completed steps do not replay on ordinary resume.
+No new checkpoint format, executor, signal hook or exactly-once guarantee is added.

moveset-0.1.0/lifecycle_tests/test_sequence.py

@@ -0,0 +1,115 @@
+import asyncio
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+
+from func_seq import Control, DefinitionMismatchError, RecoveryRequiredError, StepFailedError
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from moveset import Input, Pipeline, Ref, Step
+from moveset.sequence import compile_script
+
+
+def bind(function, *, value=None, version="1"):
+    moves = Moves()
+    moves.learn(function, name="operation")
+    return Pipeline("sequence", version="1", steps=(
+        Step("first", "operation", {"value": Input("value")}),
+        Step("second", "operation", {"value": Ref("first") if value is None else value}),
+    ), outputs={"value": Ref("second")}).bind(CapabilityCatalog(moves, ["operation"]), catalog_version=version)
+
+
+class LifecycleTests(unittest.TestCase):
+    def test_fresh_process_resume_and_identity(self):
+        with tempfile.TemporaryDirectory() as directory:
+            checkpoint, receipt = str(Path(directory) / "checkpoint.json"), str(Path(directory) / "receipt.txt")
+            def run(mode, version="v1"):
+                return subprocess.run([sys.executable, "-I", str(Path(__file__).with_name("worker.py")), checkpoint, receipt, mode, version], capture_output=True, text=True)
+            first = run("pause")
+            self.assertEqual(first.returncode, 0, first.stderr)
+            self.assertIn('"paused"', first.stdout)
+            for mode, version in (("input", "v1"), ("run", "v2")):
+                mismatch = run(mode, version)
+                self.assertNotEqual(mismatch.returncode, 0)
+                self.assertIn("DefinitionMismatchError", mismatch.stderr)
+            resumed = run("run")
+            self.assertEqual(resumed.returncode, 0, resumed.stderr)
+            self.assertEqual(Path(receipt).read_text().splitlines(), ["hello", "hello"])
+            self.assertEqual(run("run").returncode, 0)
+            self.assertEqual(Path(receipt).read_text().splitlines(), ["hello", "hello"])
+
+    def test_mapping_mismatch_pause_retry_restart_and_outputs(self):
+        calls = []
+
+        def operation(value: str) -> str:
+            calls.append(value)
+            return value
+
+        bound = bind(operation)
+        with tempfile.TemporaryDirectory() as directory:
+            checkpoint = Path(directory) / "checkpoint.json"
+            control = Control()
+            def observer(event):
+                if event.kind == "finished":
+                    control.request_pause()
+            first = compile_script(bound, {"value": "hi"}).run(checkpoint=checkpoint, control=control, observer=observer)
+            self.assertEqual(first.status, "paused")
+            with self.assertRaises(DefinitionMismatchError):
+                compile_script(bind(operation, value="different"), {"value": "hi"}).run(checkpoint=checkpoint)
+            result = compile_script(bound, {"value": "hi"}).run(checkpoint=checkpoint)
+            self.assertEqual(bound.finish({"value": "hi"}, result.results).outputs, {"value": "hi"})
+            self.assertEqual(calls, ["hi", "hi"])
+            compile_script(bound, {"value": "hi"}).run(checkpoint=checkpoint, restart=True)
+            self.assertEqual(len(calls), 4)
+
+    def test_failed_effect_requires_explicit_retry(self):
+        calls = []
+
+        def effect(value: str) -> str:
+            calls.append(value)
+            if len(calls) == 1:
+                raise RuntimeError("after effect")
+            return value
+
+        script = compile_script(bind(effect), {"value": "x"})
+        with self.assertRaises(StepFailedError):
+            script.run()
+        with self.assertRaises(RecoveryRequiredError):
+            script.run()
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(script.run(retry=True).status, "completed")
+        self.assertEqual(len(calls), 3)
+
+
+class AsyncLifecycleTests(unittest.IsolatedAsyncioTestCase):
+    async def test_mixed_async_and_cancellation_uncertainty(self):
+        calls = []
+
+        def first(value: str) -> str:
+            calls.append("sync")
+            return value
+
+        async def second(value: str) -> str:
+            await asyncio.sleep(0)
+            calls.append("async")
+            return value.upper()
+
+        moves = Moves()
+        moves.learn(first)
+        moves.learn(second)
+        bound = Pipeline("mixed", version="1", steps=(Step("a", "first", {"value": "hello"}),
+            Step("b", "second", {"value": Ref("a")})), outputs={"value": Ref("b")}).bind(CapabilityCatalog(moves, ["first", "second"]), catalog_version="1")
+        result = await compile_script(bound, {}, asynchronous=True).arun()
+        self.assertEqual(calls, ["sync", "async"])
+        self.assertEqual(result.results["b"], "HELLO")
+
+        async def cancel(value: str) -> str:
+            raise asyncio.CancelledError
+
+        script = compile_script(bind(cancel), {"value": "x"}, asynchronous=True)
+        with self.assertRaises(asyncio.CancelledError):
+            await script.arun()
+        with self.assertRaises(RecoveryRequiredError):
+            await script.arun()

moveset-0.1.0/lifecycle_tests/worker.py

@@ -0,0 +1,33 @@
+"""Synthetic effects for actual independent-process checkpoint tests."""
+
+import json
+from pathlib import Path
+import sys
+
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from moveset import Input, Pipeline, Ref, Step
+from moveset.sequence import compile_script
+
+
+def effect(value: str, receipt: str) -> str:
+    with Path(receipt).open("a", encoding="utf-8") as output:
+        output.write(value + "\n")
+    return value
+
+
+def main():
+    checkpoint, receipt, mode, catalog_version = sys.argv[1:]
+    moves = Moves()
+    moves.learn(effect)
+    bound = Pipeline("processes", version="1", steps=(
+        Step("first", "effect", {"value": Input("text"), "receipt": receipt}),
+        Step("second", "effect", {"value": Ref("first"), "receipt": receipt}),
+    ), outputs={"text": Ref("second")}).bind(CapabilityCatalog(moves, ["effect"]), catalog_version=catalog_version)
+    script = compile_script(bound, {"text": "changed" if mode == "input" else "hello"})
+    result = script.run(checkpoint=checkpoint, pace="function" if mode == "pause" else "auto")
+    print(json.dumps({"status": result.status, "completed": result.completed}))
+
+
+if __name__ == "__main__":
+    main()

moveset-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "moveset"
+version = "0.1.0"
+license = "MIT"
+license-files = ["LICENSE"]
+description = "Explicit linear composition of selected Python capabilities."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["hidden-moves>=0.1.0"]
+
+[[project.authors]]
+name = "ellainng"
+
+[project.optional-dependencies]
+sequence = ["func-seq>=0.1.0 ; python_version >= '3.14'"]
+
+[project.urls]
+Source = "https://github.com/wispsy/moveset"
+Issues = "https://github.com/wispsy/moveset/issues"
+Project = "https://github.com/orgs/wispsy/projects/23"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = [
+    "LICENSE",
+    "tests/*.py",
+    "scripts/*.py",
+    "docs/*.md",
+    "lifecycle_tests/*.py",
+]

moveset-0.1.0/pyproject.toml.orig

@@ -0,0 +1,25 @@
+[project]
+name = "moveset"
+version = "0.1.0"
+license = "MIT"
+license-files = ["LICENSE"]
+description = "Explicit linear composition of selected Python capabilities."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "ellainng" }]
+dependencies = ["hidden-moves>=0.1.0"]
+
+[project.optional-dependencies]
+sequence = ["func-seq>=0.1.0 ; python_version >= '3.14'"]
+
+[project.urls]
+Source = "https://github.com/wispsy/moveset"
+Issues = "https://github.com/wispsy/moveset/issues"
+Project = "https://github.com/orgs/wispsy/projects/23"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["LICENSE", "tests/*.py", "scripts/*.py", "docs/*.md", "lifecycle_tests/*.py"]

moveset-0.1.0/scripts/qualify.py

@@ -0,0 +1,42 @@
+"""Install both artifacts outside the checkout and run public contract tests."""
+
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import zipfile
+from email.parser import BytesParser
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main():
+    directory = Path(sys.argv[1]).resolve()
+    artifacts = sorted([*directory.glob("*.whl"), *directory.glob("*.tar.gz")])
+    assert len(artifacts) == 2
+    wheel, = directory.glob("*.whl")
+    with zipfile.ZipFile(wheel) as archive:
+        assert "moveset/py.typed" in archive.namelist()
+        metadata, = [name for name in archive.namelist() if name.endswith("/METADATA")]
+        message = BytesParser().parsebytes(archive.read(metadata))
+        assert message["Name"] == "moveset"
+        assert message["Requires-Python"] == ">=3.11"
+        assert all("func-seq" not in item or "extra ==" in item for item in message.get_all("Requires-Dist", []))
+    for artifact in artifacts:
+        with tempfile.TemporaryDirectory() as temporary:
+            outside = Path(temporary)
+            environment = outside / "env"
+            subprocess.run(["uv", "venv", str(environment), "--python", sys.executable], check=True)
+            python = environment / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
+            subprocess.run(["uv", "pip", "install", "--python", str(python), str(artifact)], check=True, cwd=outside)
+            subprocess.run([str(python), "-I", "-c", "import importlib.util, moveset; assert importlib.util.find_spec('func_seq') is None"], check=True, cwd=outside)
+            subprocess.run([str(python), "-I", "-m", "unittest", "discover", "-s", str(ROOT / "tests"), "-v"], check=True, cwd=outside)
+            lifecycle = ROOT / "lifecycle_tests"
+            if sys.version_info >= (3, 14) and lifecycle.exists():
+                subprocess.run(["uv", "pip", "install", "--python", str(python), f"{artifact}[sequence]"], check=True, cwd=outside)
+                subprocess.run([str(python), "-I", "-m", "unittest", "discover", "-s", str(lifecycle), "-v"], check=True, cwd=outside)
+            subprocess.run(["uv", "pip", "check", "--python", str(python)], check=True, cwd=outside)
+
+
+if __name__ == "__main__":
+    main()

moveset-0.1.0/src/moveset/__init__.py

@@ -0,0 +1,5 @@
+"""Immutable linear pipelines over explicitly selected capability catalogs."""
+
+from .core import BoundPipeline, DefinitionError, Input, Pipeline, PipelineError, Ref, Result, Step, StepError
+
+__all__ = ["BoundPipeline", "DefinitionError", "Input", "Pipeline", "PipelineError", "Ref", "Result", "Step", "StepError"]

moveset-0.1.0/src/moveset/_validation.py

@@ -0,0 +1,121 @@
+"""Fallback JSON validation when hidden_moves does not export validate_json_value."""
+from __future__ import annotations
+import math
+from collections.abc import Mapping
+from typing import Any
+from hidden_moves.adapters.errors import CapabilityExposureError
+
+_KEYWORDS = frozenset({
+	"$schema", "title", "description", "default", "examples", "type", "enum",
+	"anyOf", "properties", "required", "additionalProperties", "items",
+})
+_TYPES = frozenset({"null", "boolean", "integer", "number", "string", "array", "object"})
+
+class ValueValidationError(ValueError):
+	"""A finite JSON value does not match the declared subset."""
+
+def check_schema(schema: Mapping[str, Any]) -> None:
+	if not isinstance(schema, Mapping):
+		raise CapabilityExposureError("Schema nodes must be objects.")
+	unknown = set(schema) - _KEYWORDS
+	if unknown:
+		raise CapabilityExposureError(f"Unsupported schema keywords: {", ".join(sorted(unknown))}.")
+	if "type" in schema:
+		types = schema["type"]
+		if isinstance(types, str):
+			types = (types,)
+		if not isinstance(types, (list, tuple)) or not types or any(
+			not isinstance(item, str) or item not in _TYPES for item in types
+		):
+			raise CapabilityExposureError("Schema type must be a supported JSON type or nonempty type list.")
+	if "enum" in schema and (not isinstance(schema["enum"], (list, tuple)) or not schema["enum"]):
+		raise CapabilityExposureError("Schema enum must be a nonempty array.")
+	if "anyOf" in schema:
+		branches = schema["anyOf"]
+		if not isinstance(branches, (list, tuple)) or not branches:
+			raise CapabilityExposureError("Schema anyOf must be a nonempty array.")
+		for branch in branches:
+			check_schema(branch)
+	properties = schema.get("properties", {})
+	if not isinstance(properties, Mapping):
+		raise CapabilityExposureError("Schema properties must be an object.")
+	for child in properties.values():
+		check_schema(child)
+	if "required" in schema:
+		required = schema["required"]
+		if not isinstance(required, (list, tuple)) or any(not isinstance(item, str) for item in required):
+			raise CapabilityExposureError("Schema required must be an array of property names.")
+		if len(required) != len(set(required)):
+			raise CapabilityExposureError("Schema required names must be unique.")
+	additional = schema.get("additionalProperties", True)
+	if not isinstance(additional, bool):
+		check_schema(additional)
+	if additional is False and any(name not in properties for name in schema.get("required", ())):
+		raise CapabilityExposureError("A closed schema requires a property it does not declare.")
+	if "items" in schema:
+		check_schema(schema["items"])
+
+def _matches(value: Any, kind: str) -> bool:
+	if kind == "null":
+		return value is None
+	if kind == "boolean":
+		return isinstance(value, bool)
+	if kind == "integer":
+		return type(value) is int or (type(value) is float and math.isfinite(value) and value.is_integer())
+	if kind == "number":
+		return type(value) is int or (type(value) is float and math.isfinite(value))
+	return isinstance(value, {"string": str, "array": list, "object": dict}[kind])
+
+def _equal(first: Any, second: Any) -> bool:
+	if isinstance(first, bool) != isinstance(second, bool):
+		return False
+	if isinstance(first, Mapping) and isinstance(second, Mapping):
+		return first.keys() == second.keys() and all(_equal(first[key], second[key]) for key in first)
+	if isinstance(first, (tuple, list)) and isinstance(second, (tuple, list)):
+		return len(first) == len(second) and all(_equal(a, b) for a, b in zip(first, second))
+	return first == second
+
+def validate_value(schema: Mapping[str, Any], value: Any, path: str = "$arguments") -> None:
+	if "type" in schema:
+		types = schema["type"]
+		types = (types,) if isinstance(types, str) else types
+		if not any(_matches(value, kind) for kind in types):
+			raise ValueValidationError(f"{path}: expected {" or ".join(types)}.")
+	if "enum" in schema and not any(_equal(value, item) for item in schema["enum"]):
+		raise ValueValidationError(f"{path}: value is outside the declared enum.")
+	if "anyOf" in schema:
+		for branch in schema["anyOf"]:
+			try:
+				validate_value(branch, value, path)
+				break
+			except ValueValidationError:
+				pass
+		else:
+			raise ValueValidationError(f"{path}: value does not match any declared type.")
+	if isinstance(value, dict):
+		properties = schema.get("properties", {})
+		for name in schema.get("required", ()):
+			if name not in value:
+				raise ValueValidationError(f"{path}.{name}: required argument is missing.")
+		additional = schema.get("additionalProperties", True)
+		for name, item in value.items():
+			if name in properties:
+				validate_value(properties[name], item, f"{path}.{name}")
+			elif additional is False:
+				raise ValueValidationError(f"{path}.{name}: unexpected argument.")
+			elif isinstance(additional, Mapping):
+				validate_value(additional, item, f"{path}.{name}")
+	if isinstance(value, list) and "items" in schema:
+		for index, item in enumerate(value):
+			validate_value(schema["items"], item, f"{path}[{index}]")
+
+def fallback_validate_json_value(schema: Mapping[str, Any], value: Any, path: str = "$value") -> Any:
+	from hidden_moves import MoveSchemaError
+	from hidden_moves.core.schema import json_value
+	check_schema(schema)
+	try:
+		copied = json_value(value)
+	except (MoveSchemaError, RecursionError) as error:
+		raise ValueValidationError(f"{path}: {error}") from error
+	validate_value(schema, copied, path)
+	return copied

moveset-0.1.0/src/moveset/core.py

@@ -0,0 +1,380 @@
+"""Explicit data mappings; capability and lifecycle behavior belongs to their owners."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import inspect
+import json
+import math
+import re
+from typing import Any
+
+from hidden_moves.adapters import CapabilityCatalog
+try:
+    from hidden_moves.adapters import validate_json_value
+except ImportError:
+    from ._validation import fallback_validate_json_value as validate_json_value
+
+MAX_BYTES = 1_048_576
+MAX_DEPTH = 32
+MAX_STEPS = 256
+
+
+class PipelineError(ValueError):
+    """A definition or value cannot be used by this pipeline."""
+
+
+class DefinitionError(PipelineError):
+    """A passive definition is invalid."""
+
+
+class StepError(PipelineError):
+    """A selected operation or one of its mappings failed."""
+
+    def __init__(self, step: Step, message: str):
+        self.step_id = step.id
+        self.capability = step.capability
+        super().__init__(f"step {step.id!r} ({step.capability}): {message}")
+
+
+def identifier(value: str) -> str:
+    if type(value) is not str or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", value):
+        raise DefinitionError("Identifiers require 1–128 ASCII letters, digits, dots, underscores or hyphens")
+    return value
+
+
+def canonical(value: Any) -> bytes:
+    try:
+        data = json.dumps(value, ensure_ascii=False, allow_nan=False, sort_keys=True,
+                          separators=(",", ":")).encode("utf-8")
+    except (TypeError, ValueError, UnicodeError, RecursionError) as error:
+        raise PipelineError("Expected finite UTF-8 JSON") from error
+    if len(data) > MAX_BYTES:
+        raise PipelineError(f"JSON exceeds {MAX_BYTES} bytes")
+    return data
+
+
+@dataclass(frozen=True)
+class Input:
+    name: str
+    path: tuple[str | int, ...] = ()
+
+    def __post_init__(self):
+        identifier(self.name)
+        _path(self.path)
+
+    def __getitem__(self, part: str | int) -> Input:
+        return Input(self.name, (*self.path, part))
+
+
+@dataclass(frozen=True)
+class Ref:
+    step: str
+    path: tuple[str | int, ...] = ()
+
+    def __post_init__(self):
+        identifier(self.step)
+        _path(self.path)
+
+    def __getitem__(self, part: str | int) -> Ref:
+        return Ref(self.step, (*self.path, part))
+
+
+def _path(path):
+    if type(path) is not tuple or len(path) > MAX_DEPTH or any(
+        type(part) not in (str, int) or (type(part) is int and part < 0) for part in path
+    ):
+        raise DefinitionError("Paths must be bounded tuples of string keys or nonnegative indexes")
+    canonical(list(path))
+
+
+@dataclass(frozen=True)
+class _Object:
+    items: tuple
+
+
+@dataclass(frozen=True)
+class _Array:
+    items: tuple
+
+
+def freeze(value, depth=0, *, expressions=True):
+    if depth > MAX_DEPTH:
+        raise DefinitionError(f"Values exceed depth {MAX_DEPTH}")
+    if expressions and isinstance(value, (Input, Ref)):
+        return value
+    if type(value) is dict:
+        if any(type(key) is not str for key in value):
+            raise DefinitionError("Object keys must be strings")
+        return _Object(tuple((key, freeze(item, depth + 1, expressions=expressions)) for key, item in value.items()))
+    if type(value) is list:
+        return _Array(tuple(freeze(item, depth + 1, expressions=expressions) for item in value))
+    if value is None or type(value) in (str, bool, int) or (type(value) is float and math.isfinite(value)):
+        canonical(value)
+        return value
+    raise DefinitionError("Values must be finite JSON or explicit Input/Ref expressions")
+
+
+def thaw(value):
+    if isinstance(value, _Object):
+        return {key: thaw(item) for key, item in value.items}
+    if isinstance(value, _Array):
+        return [thaw(item) for item in value.items]
+    return value
+
+
+def copy_json(value):
+    copied = thaw(freeze(value, expressions=False))
+    canonical(copied)
+    return copied
+
+
+def expression(value):
+    if isinstance(value, Input):
+        return {"input": {"name": value.name, "path": list(value.path)}}
+    if isinstance(value, Ref):
+        return {"ref": {"step": value.step, "path": list(value.path)}}
+    if isinstance(value, _Object):
+        return {"object": {key: expression(item) for key, item in value.items}}
+    if isinstance(value, _Array):
+        return {"array": [expression(item) for item in value.items]}
+    return {"value": value}
+
+
+def references(value):
+    if isinstance(value, (Ref, Input)):
+        yield value
+    elif isinstance(value, (_Object, _Array)):
+        for item in (item for _, item in value.items) if isinstance(value, _Object) else value.items:
+            yield from references(item)
+
+
+def resolve(value, inputs, results):
+    if isinstance(value, (Input, Ref)):
+        selected = inputs if isinstance(value, Input) else results
+        key = value.name if isinstance(value, Input) else value.step
+        try:
+            selected = selected[key]
+            for part in value.path:
+                if (type(part) is str and type(selected) is dict) or (type(part) is int and type(selected) is list):
+                    selected = selected[part]
+                else:
+                    raise KeyError(part)
+        except (KeyError, IndexError) as error:
+            raise PipelineError(f"Cannot resolve {expression(value)}") from error
+        return copy_json(selected)
+    if isinstance(value, _Object):
+        return {key: resolve(item, inputs, results) for key, item in value.items}
+    if isinstance(value, _Array):
+        return [resolve(item, inputs, results) for item in value.items]
+    return value
+
+
+@dataclass(frozen=True, init=False)
+class Step:
+    id: str
+    capability: str
+    _arguments: _Object
+
+    def __init__(self, id: str, capability: str, arguments: dict):
+        identifier(id)
+        if type(capability) is not str or not capability or len(capability) > 512:
+            raise DefinitionError("A step requires a bounded capability name")
+        if type(arguments) is not dict:
+            raise DefinitionError("Step arguments must be an object")
+        object.__setattr__(self, "id", id)
+        object.__setattr__(self, "capability", capability)
+        object.__setattr__(self, "_arguments", freeze(arguments))
+        canonical(expression(self._arguments))
+
+    @property
+    def arguments(self):
+        return thaw(self._arguments)
+
+
+@dataclass(frozen=True, init=False)
+class Pipeline:
+    name: str
+    version: str
+    steps: tuple[Step, ...]
+    _outputs: _Object
+
+    def __init__(self, name: str, *, version: str, steps: tuple[Step, ...], outputs: dict):
+        identifier(name)
+        identifier(version)
+        if type(steps) is not tuple or not 1 <= len(steps) <= MAX_STEPS or any(type(step) is not Step for step in steps):
+            raise DefinitionError(f"A pipeline requires a tuple of 1–{MAX_STEPS} Steps")
+        previous = set()
+        for step in steps:
+            if step.id in previous:
+                raise DefinitionError(f"Duplicate step {step.id!r}")
+            for ref in references(step._arguments):
+                if isinstance(ref, Ref) and ref.step not in previous:
+                    raise DefinitionError(f"step {step.id!r}: reference must name an earlier step: {ref.step!r}")
+            previous.add(step.id)
+        if type(outputs) is not dict:
+            raise DefinitionError("Outputs must be an explicit object")
+        frozen = freeze(outputs)
+        if any(isinstance(ref, Ref) and ref.step not in previous for ref in references(frozen)):
+            raise DefinitionError("Output reference names an unknown step")
+        for key, value in (("name", name), ("version", version), ("steps", steps), ("_outputs", frozen)):
+            object.__setattr__(self, key, value)
+        canonical(self.manifest)
+
+    @property
+    def outputs(self):
+        return thaw(self._outputs)
+
+    @property
+    def manifest(self):
+        return {"schema": 1, "name": self.name, "version": self.version,
+                "steps": [{"id": step.id, "capability": step.capability,
+                           "arguments": expression(step._arguments)} for step in self.steps],
+                "outputs": expression(self._outputs)}
+
+    def bind(self, catalog: CapabilityCatalog, *, catalog_version: str) -> BoundPipeline:
+        return BoundPipeline(self, catalog, catalog_version)
+
+
+def _partial(schema, value, inputs=None):
+    """Validate known portions; unknown producer values are checked at invocation."""
+    if isinstance(value, Ref):
+        return
+    if isinstance(value, Input):
+        if inputs is not None:
+            validate_json_value(schema, resolve(value, inputs, {}))
+        return
+    if "anyOf" in schema:
+        for branch in schema["anyOf"]:
+            try:
+                _partial(branch, value, inputs)
+                break
+            except (ValueError, TypeError):
+                pass
+        else:
+            raise DefinitionError("Mapping does not match any declared type")
+    if isinstance(value, _Object):
+        values = dict(value.items)
+        if "type" in schema:
+            validate_json_value({"type": schema["type"]}, {})
+        if any(name not in values for name in schema.get("required", ())):
+            raise DefinitionError("A required argument is missing")
+        properties = schema.get("properties", {})
+        additional = schema.get("additionalProperties", True)
+        for key, item in value.items:
+            if key not in properties and additional is False:
+                raise DefinitionError(f"Unexpected argument {key!r}")
+            _partial(properties.get(key, additional if isinstance(additional, dict) else {}), item, inputs)
+    elif isinstance(value, _Array):
+        if "type" in schema:
+            validate_json_value({"type": schema["type"]}, [])
+        for item in value.items:
+            _partial(schema.get("items", {}), item, inputs)
+    else:
+        validate_json_value(schema, value)
+    if not tuple(references(value)):
+        validate_json_value(schema, thaw(value))
+
+
+@dataclass(frozen=True)
+class Result:
+    """A run's caller-owned JSON snapshots."""
+
+    results: dict
+    outputs: dict
+
+
+@dataclass(frozen=True, init=False)
+class BoundPipeline:
+    definition: Pipeline
+    catalog: CapabilityCatalog
+    catalog_version: str
+
+    def __init__(self, definition, catalog, catalog_version):
+        if not isinstance(catalog, CapabilityCatalog):
+            raise DefinitionError("Bind an explicitly selected CapabilityCatalog")
+        identifier(catalog_version)
+        for step in definition.steps:
+            try:
+                schema = _schema_json(catalog.describe(step.capability).input_schema)
+                _partial(schema, step._arguments)
+            except Exception as error:
+                raise StepError(step, str(error)) from error
+        object.__setattr__(self, "definition", definition)
+        object.__setattr__(self, "catalog", catalog)
+        object.__setattr__(self, "catalog_version", catalog_version)
+        canonical(self.manifest)
+
+    @property
+    def manifest(self):
+        names = sorted({step.capability for step in self.definition.steps})
+        return {"definition": self.definition.manifest, "catalog_version": self.catalog_version,
+                "capabilities": [{"name": name, "input": _schema_json(self.catalog.describe(name).input_schema),
+                                  "output": _schema_json(self.catalog.describe(name).output_schema),
+                                  "async": self.catalog.describe(name).is_async} for name in names]}
+
+    @property
+    def fingerprint(self):
+        return hashlib.sha256(canonical(self.manifest)).hexdigest()
+
+    def prepare(self, inputs: dict):
+        if type(inputs) is not dict:
+            raise PipelineError("Run inputs must be a JSON object")
+        inputs = copy_json(inputs)
+        for step in self.definition.steps:
+            try:
+                _partial(_schema_json(self.catalog.describe(step.capability).input_schema), step._arguments, inputs)
+            except Exception as error:
+                raise StepError(step, str(error)) from error
+        for ref in references(self.definition._outputs):
+            if isinstance(ref, Input):
+                resolve(ref, inputs, {})
+        return inputs
+
+    def finish(self, inputs, results):
+        return Result(copy_json(results), resolve(self.definition._outputs, inputs, results))
+
+    def _invoke(self, step, inputs, results):
+        return self.catalog.invoke(step.capability, resolve(step._arguments, inputs, results))
+
+    def run(self, inputs: dict) -> Result:
+        inputs = self.prepare(inputs)
+        if any(self.catalog.describe(step.capability).is_async for step in self.definition.steps):
+            raise DefinitionError("Pipeline contains async capabilities; use arun()")
+        results = {}
+        for step in self.definition.steps:
+            try:
+                result = self._invoke(step, inputs, results)
+                if inspect.isawaitable(result):
+                    if inspect.iscoroutine(result):
+                        result.close()
+                    raise DefinitionError("Capability returned an awaitable; use arun()")
+                results[step.id] = copy_json(self.catalog.serialize_result(step.capability, result))
+            except Exception as error:
+                raise StepError(step, str(error)) from error
+        return self.finish(inputs, results)
+
+    async def arun(self, inputs: dict) -> Result:
+        inputs = self.prepare(inputs)
+        results = {}
+        for step in self.definition.steps:
+            try:
+                result = self._invoke(step, inputs, results)
+                if inspect.isawaitable(result):
+                    result = await result
+                results[step.id] = copy_json(self.catalog.serialize_result(step.capability, result))
+            except Exception as error:
+                raise StepError(step, str(error)) from error
+        return self.finish(inputs, results)
+
+
+def _schema_json(schema):
+    """Catalog metadata uses frozen mappings/tuples; normalize without changing values."""
+    from collections.abc import Mapping
+
+    if isinstance(schema, Mapping):
+        return {key: _schema_json(item) for key, item in schema.items()}
+    if isinstance(schema, (list, tuple)):
+        return [_schema_json(item) for item in schema]
+    return schema

moveset-0.1.0/src/moveset/sequence.py

@@ -0,0 +1,70 @@
+"""Optional compilation into func_seq's public Script and lifecycle contract."""
+
+import sys
+
+if sys.version_info < (3, 14):
+    raise ImportError("The moveset sequence adapter requires Python 3.14 or newer")
+
+import hashlib
+import inspect
+
+from func_seq import Ref as SequenceRef, Script
+
+from .core import BoundPipeline, DefinitionError, Input, Ref, StepError, _Array, _Object, canonical, copy_json, resolve
+
+
+def _mapping(value, inputs):
+    if isinstance(value, Input):
+        return resolve(value, inputs, {})
+    if isinstance(value, Ref):
+        return SequenceRef(value.step, value.path)
+    if isinstance(value, _Object):
+        return {key: _mapping(item, inputs) for key, item in value.items}
+    if isinstance(value, _Array):
+        return [_mapping(item, inputs) for item in value.items]
+    return value
+
+
+def _wrapper(bound, step, asynchronous):
+    def invoke(arguments):
+        try:
+            result = bound.catalog.invoke(step.capability, arguments)
+            if inspect.isawaitable(result):
+                if inspect.iscoroutine(result):
+                    result.close()
+                raise DefinitionError("Capability returned an awaitable; compile with asynchronous=True")
+            return copy_json(bound.catalog.serialize_result(step.capability, result))
+        except Exception as error:
+            raise StepError(step, str(error)) from error
+
+    async def ainvoke(arguments):
+        try:
+            result = bound.catalog.invoke(step.capability, arguments)
+            if inspect.isawaitable(result):
+                result = await result
+            return copy_json(bound.catalog.serialize_result(step.capability, result))
+        except Exception as error:
+            raise StepError(step, str(error)) from error
+
+    return ainvoke if asynchronous else invoke
+
+
+def compile_script(bound: BoundPipeline, inputs: dict, *, asynchronous: bool = False) -> Script:
+    """Compile validated mappings; return func_seq's executor without wrapping state.
+
+    Use asynchronous=True with Script.arun for mixed/awaitable capabilities. The
+    execution mode is part of compatibility identity. Control, pace, observers,
+    checkpoint, retry and restart are passed directly to Script.run/arun.
+    """
+    if type(asynchronous) is not bool:
+        raise DefinitionError("asynchronous must be a boolean")
+    inputs = bound.prepare(inputs)
+    if not asynchronous and any(bound.catalog.describe(step.capability).is_async for step in bound.definition.steps):
+        raise DefinitionError("Async capabilities require asynchronous=True and Script.arun")
+    version = hashlib.sha256(canonical({"pipeline": bound.fingerprint, "inputs": inputs,
+                                       "asynchronous": asynchronous})).hexdigest()
+    script = Script(bound.definition.name, version=version)
+    for step in bound.definition.steps:
+        script.add_function(_wrapper(bound, step, asynchronous),
+                            _mapping(step._arguments, inputs), step_id=step.id)
+    return script

moveset-0.1.0/tests/test_pipeline.py

@@ -0,0 +1,170 @@
+import asyncio
+from dataclasses import FrozenInstanceError
+import unittest
+
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from moveset import DefinitionError, Input, Pipeline, PipelineError, Ref, Step, StepError
+
+
+def catalog(**functions):
+    moves = Moves()
+    for name, function in functions.items():
+        moves.learn(function, name=name)
+    return CapabilityCatalog(moves, functions)
+
+
+def normalize(text: str) -> str:
+    return " ".join(text.lower().split())
+
+
+def report(text: str) -> dict[str, str]:
+    return {"text": text}
+
+
+def definition():
+    return Pipeline("text", version="1", steps=(
+        Step("normalize", "normalize", {"text": Input("text")}),
+        Step("report", "report", {"text": Ref("normalize")}),
+    ), outputs={"report": Ref("report")})
+
+
+class PipelineTests(unittest.TestCase):
+    def test_reuses_ordinary_functions_and_preserves_scalar_records(self):
+        bound = definition().bind(catalog(normalize=normalize, report=report), catalog_version="v1")
+        self.assertEqual(normalize(" Hi THERE "), "hi there")
+        result = bound.run({"text": " Hi THERE "})
+        self.assertEqual(result.results, {"normalize": "hi there", "report": {"text": "hi there"}})
+        self.assertEqual(result.outputs, {"report": {"text": "hi there"}})
+        result.results["report"]["text"] = "changed"
+        self.assertEqual(result.outputs["report"]["text"], "hi there")
+        self.assertEqual(bound.run({"text": "x"}).outputs["report"]["text"], "x")
+
+    def test_definition_is_deeply_immutable(self):
+        arguments = {"text": "before"}
+        step = Step("first", "normalize", arguments)
+        pipeline = Pipeline("copy", version="1", steps=(step,), outputs={"result": Ref("first")})
+        arguments["text"] = "after"
+        step.arguments["text"] = "also after"
+        pipeline.outputs["new"] = 2
+        pipeline.manifest["steps"].clear()
+        self.assertEqual(step.arguments["text"], "before")
+        self.assertEqual(pipeline.outputs, {"result": Ref("first")})
+        with self.assertRaises(FrozenInstanceError):
+            step.id = "other"
+
+    def test_static_errors_happen_without_invocation(self):
+        calls = []
+
+        def effect(text: str) -> str:
+            calls.append(text)
+            return text
+
+        selected = catalog(effect=effect)
+        for arguments in ({}, {"text": 1}, {"text": "x", "extra": Ref("first")}):
+            with self.subTest(arguments=arguments), self.assertRaises(PipelineError):
+                Pipeline("bad", version="1", steps=(Step("first", "effect", {"text": "x"}),
+                    Step("second", "effect", arguments)), outputs={}).bind(selected, catalog_version="1")
+        bound = Pipeline("inputs", version="1", steps=(Step("first", "effect", {"text": "x"}),
+            Step("second", "effect", {"text": Input("missing")})), outputs={}).bind(selected, catalog_version="1")
+        with self.assertRaises(StepError):
+            bound.run({})
+        with self.assertRaises(StepError):
+            bound.run({"missing": False})
+        self.assertEqual(calls, [])
+        with self.assertRaises(StepError):
+            definition().bind(selected, catalog_version="1")
+
+    def test_names_references_and_limits(self):
+        for name in ("", "a b", "a" * 129, True):
+            with self.assertRaises(DefinitionError):
+                Step(name, "normalize", {})
+        for path in ((True,), (-1,), ["x"]):
+            with self.assertRaises(DefinitionError):
+                Ref("first", path)
+        with self.assertRaises(DefinitionError):
+            Pipeline("bad", version="1", steps=(Step("first", "normalize", {"text": Ref("later")}),), outputs={})
+        with self.assertRaises(DefinitionError):
+            Pipeline("bad", version="1", steps=(Step("same", "normalize", {}), Step("same", "normalize", {})), outputs={})
+        for value in (float("nan"), object(), {1: "bad"}, "\ud800", "x" * 1_048_576):
+            with self.subTest(value=type(value)), self.assertRaises(PipelineError):
+                Step("bad", "normalize", {"text": value})
+
+    def test_missing_path_and_invalid_reference_type_never_call_consumer(self):
+        calls = []
+
+        def producer() -> dict[str, list[int]]:
+            calls.append("producer")
+            return {"items": [3]}
+
+        def consume(text: str) -> str:
+            calls.append("consumer")
+            return text
+
+        for ref in (Ref("first")["missing"], Ref("first")["items"][0], Ref("first")[0]):
+            calls.clear()
+            bound = Pipeline("paths", version="1", steps=(Step("first", "producer", {}),
+                Step("second", "consume", {"text": ref})), outputs={}).bind(catalog(producer=producer, consume=consume), catalog_version="1")
+            with self.assertRaises(StepError) as caught:
+                bound.run({})
+            self.assertEqual(caught.exception.step_id, "second")
+            self.assertEqual(calls, ["producer"])
+
+    def test_nested_mapping_copy_and_input_paths(self):
+        def mutate(items: list[dict[str, int]]) -> list[dict[str, int]]:
+            items[0]["x"] += 1
+            return items
+
+        inputs = {"payload": {"x": 2}}
+        bound = Pipeline("nested", version="1", steps=(Step("one", "mutate", {"items": [Input("payload")]}),
+            Step("two", "mutate", {"items": Ref("one")})), outputs={"first": Ref("one")[0]["x"], "second": Ref("two")}).bind(catalog(mutate=mutate), catalog_version="1")
+        result = bound.run(inputs)
+        self.assertEqual(result.outputs, {"first": 3, "second": [{"x": 4}]})
+        self.assertEqual(inputs, {"payload": {"x": 2}})
+
+    def test_failures_keep_context_and_cause(self):
+        def fail() -> str:
+            raise RuntimeError("failed")
+
+        bound = Pipeline("failure", version="1", steps=(Step("one", "fail", {}),), outputs={}).bind(catalog(fail=fail), catalog_version="1")
+        with self.assertRaises(StepError) as caught:
+            bound.run({})
+        self.assertIsInstance(caught.exception.__cause__, RuntimeError)
+
+    def test_fingerprint_covers_definition_mapping_schemas_and_catalog_version(self):
+        selected = catalog(normalize=normalize, report=report)
+        bound = definition().bind(selected, catalog_version="v1")
+        self.assertEqual(bound.fingerprint, definition().bind(selected, catalog_version="v1").fingerprint)
+        self.assertNotEqual(bound.fingerprint, definition().bind(selected, catalog_version="v2").fingerprint)
+        bound.manifest.clear()
+        self.assertEqual(len(bound.fingerprint), 64)
+
+
+class AsyncTests(unittest.IsolatedAsyncioTestCase):
+    async def test_mixed_order_and_sync_preflight(self):
+        calls = []
+
+        def first(text: str) -> str:
+            calls.append("first")
+            return text
+
+        async def second(text: str) -> str:
+            await asyncio.sleep(0)
+            calls.append("second")
+            return text.upper()
+
+        bound = Pipeline("mixed", version="1", steps=(Step("a", "first", {"text": "hello"}),
+            Step("b", "second", {"text": Ref("a")})), outputs={"text": Ref("b")}).bind(catalog(first=first, second=second), catalog_version="1")
+        with self.assertRaises(DefinitionError):
+            bound.run({})
+        self.assertEqual(calls, [])
+        self.assertEqual((await bound.arun({})).outputs, {"text": "HELLO"})
+        self.assertEqual(calls, ["first", "second"])
+
+    async def test_cancellation_propagates(self):
+        async def stop() -> str:
+            raise asyncio.CancelledError
+
+        bound = Pipeline("cancel", version="1", steps=(Step("one", "stop", {}),), outputs={}).bind(catalog(stop=stop), catalog_version="1")
+        with self.assertRaises(asyncio.CancelledError):
+            await bound.arun({})