necoherence 0.2.0__py3-none-any.whl

necoherence/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/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/__init__.py

@@ -0,0 +1,479 @@
+# SPDX-FileCopyrightText: 2026 barineco
+# SPDX-License-Identifier: MIT
+
+"""Revision-aware state transition utilities for Python.
+
+Ten shared feature families: core, call, iteration, store, record,
+reconcile, request progression, dynamic admission, step transition, file
+effect.
+"""
+
+from necoherence.call import (
+    BoundaryDiagnosis,
+    CallFailed,
+    CallOk,
+    CallResult,
+    Deferred,
+    Immediate,
+    ProjectionFailed,
+    Request,
+    deferred_of,
+    immediate_of,
+    io,
+    issue,
+)
+from necoherence.core import (
+    Applied,
+    Basis,
+    BoundaryFailed,
+    Command,
+    Conflicted,
+    Observation,
+    Outcome,
+    Rejected,
+    ResourceId,
+    Revision,
+    StaleBasis,
+    UnknownResource,
+    World,
+    apply,
+    bump,
+    command_of,
+    lookup,
+)
+from necoherence.dynamic_admission import (
+    AdapterBindingUnavailable,
+    AdmissionDecision,
+    AdmissionProvenance,
+    AdmissionSignal,
+    BindingSelectionMismatch,
+    CapacityObservation,
+    CapacityObservationUnavailable,
+    Coalesced,
+    CoalescedWitness,
+    CoalescingWitness,
+    ConfiguredSafetyLimitExceeded,
+    DynamicAdmissionFailure,
+    DynamicAdmissionInput,
+    DynamicAdmissionOutcome,
+    DynamicAdmissionResult,
+    DynamicAdmissionState,
+    DynamicPermissionIdentityMismatch,
+    DynamicUnknownRequest,
+    EffectiveBudget,
+    ElisionOutcome,
+    Erased,
+    EnvironmentSpecification,
+    FutureUseSet,
+    MeaningDenied,
+    NotCoalesced,
+    OutstandingSignalSet,
+    ProgressionStartFailure,
+    ProgressionSubmitFailure,
+    ProvenanceErasureWitness,
+    ProvenanceRetentionRequired,
+    RequestNotTerminal,
+    ResourceCoordinateMismatch,
+    Retained,
+    SignalKind,
+    Started as DynamicStarted,
+    Submitted,
+    admit_dynamic_request,
+    elide_admission_provenance,
+)
+from necoherence.files import (
+    ContentDigest,
+    Digests,
+    ExternalFileState,
+    ExternalMutation,
+    FileRecord,
+    FileSnapshot,
+    NormalizedPath,
+    Read,
+    ReadFailure,
+    ReadReq,
+    ReadResult,
+    ReplaceContents,
+    ReplaceReq,
+    ReplaceResult,
+    Replaced,
+    ResourcePathMismatch,
+    Tracked,
+    TrackReq,
+    TrackResult,
+    UnobservedContents,
+    lookup_digest,
+    normalize_path,
+    read,
+    replace,
+    set_digest,
+    track,
+)
+from necoherence.iteration import (
+    ClosureFixpoint,
+    ClosureOutcome,
+    ClosureProjectionFailed,
+    ClosureReq,
+    ClosureState,
+    ClosureViolation,
+    Continue,
+    FoldCountNegative,
+    FoldOutcome,
+    FoldReq,
+    FoldStopped,
+    FoldTrace,
+    MeasureNegative,
+    RecurseDidNotDecrease,
+    RecurseOutcome,
+    RecurseProjectionFailed,
+    RecurseReq,
+    RecurseSettled,
+    Settled,
+    StageProjectionFailed,
+    StepOutcome,
+    closure,
+    fold,
+    recurse,
+)
+from necoherence.reconcile import (
+    Divergence,
+    Reconciliation,
+    UnknownToWorld,
+    WorldAhead,
+    WorldBehind,
+    coherent,
+    reconcile,
+)
+from necoherence.record import (
+    CallRecord,
+    NoBasis,
+    has_edge,
+    record_of,
+    record_on_basis,
+)
+from necoherence.request_progression import (
+    Accepted, AdapterCommand, AdapterFailed, AdapterFailure, AdapterResult,
+    AdapterSignal, AppliedResult, AppliedSignal, CancelCommand, CancelDecisionResult,
+    CancelFailure, CancelIssued, CancelRejected, CancelUnknownRequest,
+    CancelledAtAdapter, CancelledResult, CancelledWithoutAdapter,
+    CancellationAdapterFailure, CancellationAdapterFailureObserved,
+    CompletionAdapterFailure, CompletionAdapterFailureObserved,
+    CompletionIdentityMismatch, CompletionNotRunning, CompletionObservationFailed,
+    CompletionObservationFailure, CompletionObservationResult, CompletionSignalMismatch,
+    ConcurrentLimitExceeded, ConfiguredSafetyLimit, CostSelection,
+    CostSelectionIdentityMismatch, Deferred as StartDeferred, Denied, DuplicateIdentity,
+    EvidenceVersion, Execute, ExecuteNow, ExecutionHandle, HandleMismatch,
+    InFlightLimitExceeded, MeaningPermission, MissingExecutionHandle, Ordered,
+    PendingLimitExceeded, PermissionDenial, PermissionDenied,
+    PermissionIdentityMismatch, PermissionNotOrdered, Permitted, PolicyOrderBlocked,
+    Publishing, RemainPending, RequestAlreadyTerminal, RequestEffectClass,
+    RequestEntry, RequestFootprint, RequestIdentity, RequestInput, RequestNotPending,
+    RequestNotStarting, RequestPhase, RequestPolicy, RequestProgressionSnapshot,
+    ResourceBudget, ResourceDemand, Running, Started, Starting, StartAdapterFailure,
+    StartAdapterFailureObserved, StartCommand, StartDecisionFailure,
+    StartDecisionRejected, StartDecisionResult, StartIdentityMismatch,
+    StartObservationFailed, StartObservationFailure, StartObservationResult,
+    StartSignalMismatch, SubmitAccepted, SubmitFailure, SubmitRejected, SubmitResult,
+    SupersededResult, UnknownCompletion, UnknownRequest, apply_completion_observation,
+    apply_start_observation, decide_cancel, decide_start, derive_concurrent,
+    derive_in_flight, derive_pending, empty, submit,
+)
+from necoherence.store import (
+    Found,
+    Observed,
+    Store,
+    Unknown,
+    observe,
+    store_entries,
+    store_of,
+    world_of_store,
+)
+from necoherence.transition import (
+    Capacity,
+    CapacityExceeded,
+    CapacityNegative,
+    Consumed,
+    Consumption,
+    LimitNotPositive,
+    PositiveLimit,
+    Reprocess,
+    ReprocessLimitExhausted,
+    StepFailed,
+    StepFailure,
+    StepSettled,
+    StepTransition,
+    step,
+)
+from necoherence.signature_support import GenerationFailure
+
+__all__ = [
+    "GenerationFailure",
+    "Accepted",
+    "AdapterBindingUnavailable",
+    "AdapterCommand",
+    "AdapterFailed",
+    "AdapterFailure",
+    "AdapterResult",
+    "AdapterSignal",
+    "AdmissionDecision",
+    "AdmissionProvenance",
+    "AdmissionSignal",
+    "Applied",
+    "AppliedResult",
+    "AppliedSignal",
+    "Basis",
+    "BindingSelectionMismatch",
+    "BoundaryDiagnosis",
+    "BoundaryFailed",
+    "CallRecord",
+    "CancelCommand",
+    "CancelDecisionResult",
+    "CancelFailure",
+    "CancelIssued",
+    "CancelRejected",
+    "CancelUnknownRequest",
+    "CancelledAtAdapter",
+    "CancelledResult",
+    "CancelledWithoutAdapter",
+    "CancellationAdapterFailure",
+    "CancellationAdapterFailureObserved",
+    "CallFailed",
+    "CallOk",
+    "CallResult",
+    "Capacity",
+    "CapacityExceeded",
+    "CapacityNegative",
+    "CapacityObservation",
+    "CapacityObservationUnavailable",
+    "ClosureFixpoint",
+    "ClosureOutcome",
+    "ClosureProjectionFailed",
+    "ClosureReq",
+    "ClosureState",
+    "ClosureViolation",
+    "Coalesced",
+    "CoalescedWitness",
+    "CoalescingWitness",
+    "Command",
+    "CompletionAdapterFailure",
+    "CompletionAdapterFailureObserved",
+    "CompletionIdentityMismatch",
+    "CompletionNotRunning",
+    "CompletionObservationFailed",
+    "CompletionObservationFailure",
+    "CompletionObservationResult",
+    "CompletionSignalMismatch",
+    "ConfiguredSafetyLimit",
+    "ConfiguredSafetyLimitExceeded",
+    "ConcurrentLimitExceeded",
+    "Conflicted",
+    "Consumed",
+    "Consumption",
+    "ContentDigest",
+    "Continue",
+    "CostSelection",
+    "CostSelectionIdentityMismatch",
+    "StartDeferred",
+    "Denied",
+    "Digests",
+    "Divergence",
+    "DuplicateIdentity",
+    "DynamicAdmissionFailure",
+    "DynamicAdmissionInput",
+    "DynamicAdmissionOutcome",
+    "DynamicAdmissionResult",
+    "DynamicAdmissionState",
+    "DynamicPermissionIdentityMismatch",
+    "DynamicStarted",
+    "DynamicUnknownRequest",
+    "EffectiveBudget",
+    "ElisionOutcome",
+    "EnvironmentSpecification",
+    "Erased",
+    "EvidenceVersion",
+    "Execute",
+    "ExecuteNow",
+    "ExecutionHandle",
+    "ExternalFileState",
+    "ExternalMutation",
+    "FileRecord",
+    "FileSnapshot",
+    "Found",
+    "FoldCountNegative",
+    "FoldOutcome",
+    "FoldReq",
+    "FoldStopped",
+    "FoldTrace",
+    "FutureUseSet",
+    "HandleMismatch",
+    "Immediate",
+    "InFlightLimitExceeded",
+    "LimitNotPositive",
+    "MeasureNegative",
+    "MeaningDenied",
+    "MeaningPermission",
+    "MissingExecutionHandle",
+    "NoBasis",
+    "NormalizedPath",
+    "NotCoalesced",
+    "Observation",
+    "Observed",
+    "Ordered",
+    "Outcome",
+    "OutstandingSignalSet",
+    "PendingLimitExceeded",
+    "PermissionDenial",
+    "PermissionDenied",
+    "PermissionIdentityMismatch",
+    "PermissionNotOrdered",
+    "Permitted",
+    "PolicyOrderBlocked",
+    "PositiveLimit",
+    "ProgressionStartFailure",
+    "ProgressionSubmitFailure",
+    "ProjectionFailed",
+    "ProvenanceErasureWitness",
+    "ProvenanceRetentionRequired",
+    "Publishing",
+    "Read",
+    "ReadFailure",
+    "ReadReq",
+    "ReadResult",
+    "Reconciliation",
+    "Request",
+    "RecurseDidNotDecrease",
+    "RecurseOutcome",
+    "RecurseProjectionFailed",
+    "RecurseReq",
+    "RecurseSettled",
+    "Rejected",
+    "RemainPending",
+    "ReplaceContents",
+    "ReplaceReq",
+    "ReplaceResult",
+    "Replaced",
+    "Reprocess",
+    "ReprocessLimitExhausted",
+    "RequestAlreadyTerminal",
+    "RequestEffectClass",
+    "RequestEntry",
+    "RequestFootprint",
+    "RequestIdentity",
+    "RequestInput",
+    "RequestNotPending",
+    "RequestNotStarting",
+    "RequestNotTerminal",
+    "RequestPhase",
+    "RequestPolicy",
+    "RequestProgressionSnapshot",
+    "ResourceBudget",
+    "ResourceCoordinateMismatch",
+    "ResourceDemand",
+    "ResourceId",
+    "ResourcePathMismatch",
+    "Retained",
+    "Revision",
+    "Running",
+    "Settled",
+    "SignalKind",
+    "StageProjectionFailed",
+    "StaleBasis",
+    "StartAdapterFailure",
+    "StartAdapterFailureObserved",
+    "StartCommand",
+    "StartDecisionFailure",
+    "StartDecisionRejected",
+    "StartDecisionResult",
+    "StartIdentityMismatch",
+    "StartObservationFailed",
+    "StartObservationFailure",
+    "StartObservationResult",
+    "StartSignalMismatch",
+    "Started",
+    "Starting",
+    "StepFailed",
+    "StepFailure",
+    "StepOutcome",
+    "StepSettled",
+    "StepTransition",
+    "Store",
+    "SubmitAccepted",
+    "SubmitFailure",
+    "SubmitRejected",
+    "SubmitResult",
+    "Submitted",
+    "SupersededResult",
+    "TrackReq",
+    "TrackResult",
+    "Tracked",
+    "UnknownCompletion",
+    "UnknownRequest",
+    "UnknownResource",
+    "UnknownToWorld",
+    "Unknown",
+    "UnobservedContents",
+    "World",
+    "WorldAhead",
+    "WorldBehind",
+    "admit_dynamic_request",
+    "apply",
+    "apply_completion_observation",
+    "apply_start_observation",
+    "bump",
+    "closure",
+    "coherent",
+    "command_of",
+    "decide_cancel",
+    "decide_start",
+    "deferred_of",
+    "derive_concurrent",
+    "derive_in_flight",
+    "derive_pending",
+    "elide_admission_provenance",
+    "empty",
+    "fold",
+    "has_edge",
+    "immediate_of",
+    "io",
+    "issue",
+    "lookup",
+    "lookup_digest",
+    "normalize_path",
+    "observe",
+    "read",
+    "reconcile",
+    "record_of",
+    "record_on_basis",
+    "recurse",
+    "replace",
+    "set_digest",
+    "step",
+    "store_entries",
+    "store_of",
+    "submit",
+    "track",
+]
+
+from .type_signatures import (
+    TypeSignatureLibrary, ExpectedSignatureBasis, CheckedSignatureGeneration,
+    admit_signature_generation, checkLibrary, checkProfile, decode_diagnostic,
+    decode_generation, decode_library, decode_profile, decode_profile_artifact,
+    decode_signature_basis, decode_value_condition, encode_diagnostic,
+    encode_generation, encode_library, encode_profile, encode_signature_basis,
+    encode_value_condition, signature_basis, value_semantic_profile,
+)
+from .signature_values import (
+    Completed, Ready, SealedForm, TagModel, Wrapper,
+    selectBranch, withMember, wrapDecode, wrapEncode,
+)
+
+__all__ += [
+    "TypeSignatureLibrary", "ExpectedSignatureBasis", "CheckedSignatureGeneration",
+    "admit_signature_generation", "checkLibrary", "checkProfile", "decode_diagnostic",
+    "decode_generation", "decode_library", "decode_profile", "decode_profile_artifact",
+    "decode_signature_basis", "decode_value_condition", "encode_diagnostic",
+    "encode_generation", "encode_library", "encode_profile", "encode_signature_basis",
+    "encode_value_condition", "signature_basis", "value_semantic_profile",
+    "Completed", "Ready", "SealedForm", "TagModel", "Wrapper",
+    "selectBranch", "withMember", "wrapDecode", "wrapEncode",
+]