necoherence 0.2.0__tar.gz

necoherence-0.2.0/.gitignore

@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 barineco
+# SPDX-License-Identifier: MIT
+
+__pycache__/
+*.egg-info/
+.venv/
+lean/.lake
+rust/target/
+typescript/node_modules/
+typescript/dist/
+typescript/.package-consumer/
+typescript/*.tgz
+python/dist/
+python-http-adapter/dist/
+python-http-adapter/.clean-install*/
+python-http-adapter/.pytest_cache/
+python-http-adapter/.mypy_cache/
+typescript-http-adapter/node_modules/
+typescript-http-adapter/dist/
+typescript-http-adapter/*.tgz
+typescript-http-adapter/.package-consumer/
+java-http-adapter/build/
+gleam-http-adapter/build
+gleam-http-adapter/*.tar
+python/.clean-install*/
+python/.verify-*/
+java/build/
+java/lib/
+gleam/build
+gleam/*.tar
+tools/lean/.lake
+tools/rust/target/
+tools/gleam/build
+tools/gleam/*.tar
+tools/typescript/node_modules/
+tools/typescript/dist/
+tools/typescript/.package-consumer/
+tools/typescript/*.tgz
+tools/python/dist/
+tools/python/.clean-install*/
+tools/python/.verify-*/
+tools/python/.pytest_cache/
+tools/python/.mypy_cache/
+tools/java/build/
+tools/java/lib/
+comparison/network_effect/gleam_driver/build
+comparison/network_effect/java_driver/classes/
+comparison/network_effect/rust_driver/target/
+comparison/declaration/gleam_driver/build
+comparison/declaration/rust_driver/target
+comparison/shared_operations/gleam_driver/build
+comparison/shared_operations/lean_driver/.lake
+comparison/shared_operations/rust_driver/target/
+residual-coherence/dist/
+residual-coherence/*.egg-info/
+residual-coherence/.clean-install*/
+residual-coherence/.pytest_cache/
+residual-coherence/.mypy_cache/

necoherence-0.2.0/LICENSE

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

necoherence-0.2.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: necoherence
+Version: 0.2.0
+Summary: Revision-aware state transition utilities for Python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'

necoherence-0.2.0/README-ja.md

@@ -0,0 +1,66 @@
+# Python 向けの Necoherence
+
+[プロジェクトの概要](https://github.com/barineco/necoherence/blob/publish/README-ja.md) | [English](README.md)
+
+このパッケージは、Necoherence の Python による実装で、Python 3.12 以降で使えます。
+実行時に使うのは、標準ライブラリだけです。
+
+## 意味プロファイルの受け入れ
+
+呼び出し側は、宣言を復号するときと、生成したライブラリを受け入れるときに、版の付いた意味プロファイルを渡します。
+検証、符号化と復号、実行で使う転送形式は、受け入れたプロファイルが定めます。
+
+期待するプロファイルの参照、出典、信頼するバイト列は、入力のバイト列とは別の引数として渡します。
+
+```python
+from necoherence.signature_values import ValueContext
+from necoherence.type_signatures import checkLibrary, decode_profile_artifact
+
+def decide(expected, sources, trusted, input_bytes, library, type_id, value):
+    profile = decode_profile_artifact(expected, sources, trusted, input_bytes)
+    checked = checkLibrary({**library, "profile": profile})
+    context = ValueContext({
+        "profile": checked.value["profile"], "nodes": checked.value["nodes"],
+    })
+    return context.validate(type_id, value)
+```
+
+失敗の型は、原因ごとに次のとおりです。
+
+- `WireFailure`: プロファイルの転送値の形式が誤っている
+- `DeclarationFailure`: プロファイルかライブラリが、宣言の条件に違反している
+- `AdmissionFailure`: プロファイルが、期待した参照や出典と食い違っている
+- `MeaningFailure`: 型に意味の定義が欠けている
+- `ValueFailure`: 値が検証で拒否された
+
+## その他の機能
+
+[プロジェクトの概要](https://github.com/barineco/necoherence/blob/publish/README-ja.md) に挙げた機能のほかに、次の機能があります。
+
+- 宣言の検査: 識別子の重複や、宣言にない型や定義への参照など、型と操作の宣言の誤りを検出する
+- 生成したコードのランタイム: 生成した Python のコードが実行時に呼び出す、値の検証とコーデックの共通の処理
+
+任意の [HTTP アダプター](../python-http-adapter/) は、`necoherence-http-adapter` として独立に配布します。ネットワーク副作用のコマンドを実行し、観測を核の台帳へ返します。
+
+## 付属のツール
+
+型と操作の宣言から Python の型とコーデックを生成する生成器は、[tools/](https://github.com/barineco/necoherence/tree/publish/tools) にあります。
+ライセンスは AGPL-3.0-only です。
+
+## 使用例
+
+使用例は [examples/](https://github.com/barineco/necoherence/tree/publish/python/examples) にあります。
+
+## テストと型検査
+
+次のコマンドで、テストと型検査を実行します。
+
+```bash
+python3 -m pip install ".[dev]"
+python3 -m pytest -q
+python3 -m mypy src tests
+```
+
+## ライセンス
+
+[MIT](LICENSE)

necoherence-0.2.0/README.md

@@ -0,0 +1,66 @@
+# Necoherence for Python
+
+[Project overview](https://github.com/barineco/necoherence/blob/publish/README.md) | [日本語](README-ja.md)
+
+This package is the Python implementation of Necoherence, for Python 3.12 or later.
+It uses only the standard library at run time.
+
+## Accepting a semantic profile
+
+The caller passes a versioned semantic profile when decoding declarations and when accepting a generated library.
+The accepted profile defines the wire format used by validation, encoding and decoding, and execution.
+
+The expected profile reference, the sources, and the trusted bytes are passed as arguments separate from the input bytes.
+
+```python
+from necoherence.signature_values import ValueContext
+from necoherence.type_signatures import checkLibrary, decode_profile_artifact
+
+def decide(expected, sources, trusted, input_bytes, library, type_id, value):
+    profile = decode_profile_artifact(expected, sources, trusted, input_bytes)
+    checked = checkLibrary({**library, "profile": profile})
+    context = ValueContext({
+        "profile": checked.value["profile"], "nodes": checked.value["nodes"],
+    })
+    return context.validate(type_id, value)
+```
+
+Failures are returned as the following types, one for each cause:
+
+- `WireFailure`: the profile's wire value is malformed
+- `DeclarationFailure`: the profile or the library violates a declaration condition
+- `AdmissionFailure`: the profile differs from the expected reference or sources
+- `MeaningFailure`: a type lacks a definition of its meaning
+- `ValueFailure`: validation rejected the value
+
+## Other features
+
+Besides the features listed in the [project overview](https://github.com/barineco/necoherence/blob/publish/README.md), the package provides the following:
+
+- Declaration checking: detects errors in declarations of types and operations, such as duplicate identifiers and references to undeclared types or definitions
+- Runtime for generated code: the shared value validation and codec routines that generated Python code calls at run time
+
+The optional [HTTP adapter](../python-http-adapter/) is distributed separately as `necoherence-http-adapter`. It executes network-effect commands and returns observations to the core ledger.
+
+## Tools
+
+The generator, which produces Python types and codecs from declarations of types and operations, is in [tools/](https://github.com/barineco/necoherence/tree/publish/tools).
+Its license is AGPL-3.0-only.
+
+## Examples
+
+Examples are in [examples/](https://github.com/barineco/necoherence/tree/publish/python/examples).
+
+## Testing and type checking
+
+The following commands run the tests and the type checks:
+
+```bash
+python3 -m pip install ".[dev]"
+python3 -m pytest -q
+python3 -m mypy src tests
+```
+
+## License
+
+[MIT](LICENSE)

necoherence-0.2.0/examples/01_fold_arithmetic.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 barineco
+# SPDX-License-Identifier: MIT
+
+"""fold: accumulate a running sum across a stated number of rounds.
+
+The step is one-step-determinate addition; ``count`` is the fold's own
+input field, so the number of rounds is fixed before the first one runs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from necoherence import CallOk, FoldReq, FoldTrace, Request, fold, immediate_of, io
+
+
+@dataclass(frozen=True)
+class RunningSum:
+    total: int
+    next_term: int
+
+
+def _add_next_term(state: RunningSum) -> RunningSum:
+    return RunningSum(total=state.total + state.next_term, next_term=state.next_term + 1)
+
+
+accumulate = immediate_of("examples.fold.accumulate", (), _add_next_term)
+
+
+if __name__ == "__main__":
+    req = FoldReq(step=accumulate, seed=RunningSum(total=0, next_term=1), count=5, step_fields=())
+    result = io(fold, Request(payload=req, fields=("step", "seed", "count", "step_fields")))
+    assert isinstance(result, CallOk)
+    outcome = result.value
+    assert isinstance(outcome, FoldTrace)
+    totals = tuple(state.total for state in outcome.states)
+    print(totals)
+    assert totals == (0, 1, 3, 6, 10, 15)

necoherence-0.2.0/examples/02_recurse_gcd.py

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: 2026 barineco
+# SPDX-License-Identifier: MIT
+
+"""recurse: Euclid's algorithm, measure = the larger of the two values.
+
+Each round's measure strictly decreases (the classic Euclid argument), so
+recurse settles without any stated round count.
+"""
+
+from __future__ import annotations
+
+from necoherence import (
+    CallOk,
+    Continue,
+    Immediate,
+    RecurseReq,
+    RecurseSettled,
+    Request,
+    Settled,
+    StepOutcome,
+    io,
+    recurse,
+)
+
+
+def _euclid_step(pair: tuple[int, int]) -> StepOutcome[tuple[int, int]]:
+    a, b = pair
+    if b == 0:
+        return Settled(state=(a, b))
+    return Continue(state=(b, a % b), measure=max(a, b))
+
+
+# A tuple carries no field names, so this step declares no required fields.
+euclid_step: Immediate[tuple[int, int], StepOutcome[tuple[int, int]]] = Immediate(
+    identity="examples.recurse.euclid_step", required=(), output=_euclid_step
+)
+
+
+if __name__ == "__main__":
+    req = RecurseReq(step=euclid_step, seed=(48, 18), step_fields=())
+    result = io(recurse, Request(payload=req, fields=("step", "seed", "step_fields")))
+    assert isinstance(result, CallOk)
+    outcome = result.value
+    assert isinstance(outcome, RecurseSettled)
+    print(outcome.value)
+    assert outcome.value == (6, 0)

necoherence-0.2.0/examples/03_closure_reachability.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 barineco
+# SPDX-License-Identifier: MIT
+
+"""closure: reachable-node set as a monotone step's least fixpoint.
+
+Each round adds every node one hop from the current set; the carrier's
+size bounds the number of rounds, since the residual strictly shrinks.
+"""
+
+from __future__ import annotations
+
+from necoherence import CallOk, ClosureFixpoint, ClosureReq, ClosureState, Request, closure, immediate_of, io
+
+_edges: dict[int, frozenset[int]] = {
+    1: frozenset({2, 3}),
+    2: frozenset({4}),
+    3: frozenset({4}),
+    4: frozenset(),
+    5: frozenset(),
+}
+
+
+def _one_hop(state: ClosureState[int]) -> frozenset[int]:
+    grown = set(state.elements)
+    for node in state.elements:
+        grown |= _edges[node]
+    return frozenset(grown)
+
+
+one_hop = immediate_of("examples.closure.one_hop", ("elements",), _one_hop)
+
+
+if __name__ == "__main__":
+    req = ClosureReq(step=one_hop, carrier=frozenset(_edges), seed=frozenset({1}), step_fields=("elements",))
+    result = io(closure, Request(payload=req, fields=("step", "carrier", "seed", "step_fields")))
+    assert isinstance(result, CallOk)
+    outcome = result.value
+    assert isinstance(outcome, ClosureFixpoint)
+    print(sorted(outcome.elements))
+    assert outcome.elements == frozenset({1, 2, 3, 4})

necoherence-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2026 barineco
+# SPDX-License-Identifier: MIT
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "necoherence"
+version = "0.2.0"
+description = "Revision-aware state transition utilities for Python"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "hypothesis", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/necoherence"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"README.md" = "necoherence/README.md"
+"README-ja.md" = "necoherence/README-ja.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/necoherence", "tests", "examples", "README.md", "README-ja.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.mypy]
+mypy_path = "src"