statespec 0.4.0__tar.gz

statespec-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q

statespec-0.4.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/

statespec-0.4.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Kernel tag series: `statespec-vX.Y.Z`. Contract changes are also recorded in
+`docs/policy-artifact-contract.md`.
+
+## 0.4.0 — tag `statespec-v0.4.0` (2026-07-03)
+
+Contract-defect fix (freeze exception): `canonical()` now includes `title`, so
+`presentation_digest` is independently verifiable from the artifact and
+`diff()` can describe a title change. `semantic_digest`,
+`presentation_digest`, and envelope `schema_version: 2` are all unchanged —
+existing approval bindings are unaffected. Adds the golden contract fixture
+(`tests/fixtures/golden.policy.json`) as a canonicalisation tripwire.
+
+## 0.3.0
+
+Baseline as extracted from `ConceptPending/baseplate` tag `statespec-v0.3.0`
+(commit `2aca24e`, 2026-06-10). Policy artifact envelope `schema_version: 2`
+(`semantic_digest` + `presentation_digest`). No behavioural changes at
+extraction: import rename `app.statespec` → `statespec` and doc paths only.

statespec-0.4.0/LICENSE

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

statespec-0.4.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: statespec
+Version: 0.4.0
+Summary: Declarative lifecycle state-machine specs: one enforcement path, policy identity digests, semantic diffs
+Project-URL: Repository, https://github.com/ConceptPending/statespec
+Author-email: Nick Williamson <nick@nickw.info>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# statespec
+
+Declarative lifecycle policy for entities whose `status` moves through reviewable steps.
+A spec is plain data — states, named transitions (roles + guards), invariants — and the
+same artifact is human-readable (Mermaid / plain-English table), machine-checkable
+(`validate`), enforced through a single interpreter (`apply` / `fire`), and identified
+by content digests (`identity`) so that behavioural change is mechanically
+distinguishable from wording change.
+
+- `statespec.core` — the engine: `StateSpec`, `Transition`, `Invariant`, `apply`, `fire`, `validate`.
+- `statespec.expr` — closed guard/invariant expression grammar (compare + boolean), with a
+  versioned `Opaque` escape hatch whose body is hashed into the policy identity.
+- `statespec.identity` — `canonical()`, `semantic_digest` / `presentation_digest`,
+  `change_kind`, `diff`, and `policy_record()` (the versioned `.policy.json` envelope —
+  see `docs/policy-artifact-contract.md`, the authoritative copy of the contract).
+- `statespec.render` — Mermaid, tables, and the generated lifecycle doc.
+
+Pure Python, stdlib-only, no dependencies.
+
+## Quick start
+
+```bash
+pip install statespec
+```
+
+```python
+from statespec import StateSpec, Transition, apply, validate
+from statespec.expr import field
+
+spec = StateSpec(
+    name="review", title="Review",
+    states={"draft": "Being written", "submitted": "Awaiting review",
+            "approved": "Done"},
+    fields={"amount": "int"},
+    initial="draft", terminal=frozenset({"approved"}),
+    transitions=(
+        Transition("submit", ("draft",), "submitted",
+                   roles=frozenset({"author"})),
+        Transition("approve", ("submitted",), "approved",
+                   roles=frozenset({"reviewer"}),
+                   guard=field("amount").le(100)),
+    ),
+)
+
+assert validate(spec, known_roles=frozenset({"author", "reviewer"})) == []
+apply(spec, "approve", "submitted", frozenset({"reviewer"}), {"amount": 40})
+# -> "approved". Wrong role -> PermissionDenied; amount 500 -> GuardRejected;
+# fire() returns the same decision plus structured evidence per condition.
+```
+
+Every claim above is exercised by the test suite: the refusal taxonomy and
+its precedence in `tests/test_core.py`, the expression grammar and
+typechecking in `tests/test_expr.py`, digests/diff in `tests/test_identity.py`,
+and canonicalisation byte-stability against a golden artifact in
+`tests/test_contract_golden.py`.
+
+## Boundaries (what this does not do)
+
+statespec sits *above* concurrency and persistence. It decides whether a
+transition is legal; it does not make the write atomic or durable. It will
+not stop a race between two concurrent transitions (pair it with optimistic
+locking or a version column at the persistence layer), a forgotten lock, an
+out-of-band mutation that sets `status` around the interpreter, or a
+cross-system inconsistency. The "single enforcement path" property holds
+only if every status write in the application routes through `apply`/`fire`
+— enforce that with a repo-level convention or CI gate, not by trust. The
+digests identify *policy* change; they do not verify that deployed code
+matches the artifact — that check belongs to CI or a control plane.
+
+## Provenance
+
+Extracted from [`ConceptPending/baseplate`](https://github.com/ConceptPending/baseplate)
+branch `example/state-machine` at tag `statespec-v0.3.0` (commit `2aca24e`, 2026-06-10),
+where the kernel was developed and frozen. The only changes at extraction were the import
+rename `app.statespec` → `statespec` and doc-path adjustments. This repository is the
+kernel's authoritative home from `statespec-v0.4.0` onward; the in-tree copy in baseplate
+remains frozen at v0.3.0 as part of the reference example.
+
+## Versioning and freeze discipline
+
+Kernel tags form their own series (`statespec-vX.Y.Z`), separate from any consuming
+product's versions. The canonicalisation and digest rules are a **frozen contract**:
+any change to the policy-artifact envelope bumps `schema_version` and the kernel tag
+together, and is recorded in `docs/policy-artifact-contract.md`'s changelog. Changes
+that alter existing digests are breaking and require explicit re-binding by consumers
+(e.g. approval planes). Exceptions to the freeze: genuine bugs, security issues, or
+contract defects.
+
+Known consumers: `baseplate` (reference example, v0.3.0), `baseplate-control`
+(approval plane; vendors this kernel byte-identically and verifies digests independently).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+```

statespec-0.4.0/README.md

@@ -0,0 +1,98 @@
+# statespec
+
+Declarative lifecycle policy for entities whose `status` moves through reviewable steps.
+A spec is plain data — states, named transitions (roles + guards), invariants — and the
+same artifact is human-readable (Mermaid / plain-English table), machine-checkable
+(`validate`), enforced through a single interpreter (`apply` / `fire`), and identified
+by content digests (`identity`) so that behavioural change is mechanically
+distinguishable from wording change.
+
+- `statespec.core` — the engine: `StateSpec`, `Transition`, `Invariant`, `apply`, `fire`, `validate`.
+- `statespec.expr` — closed guard/invariant expression grammar (compare + boolean), with a
+  versioned `Opaque` escape hatch whose body is hashed into the policy identity.
+- `statespec.identity` — `canonical()`, `semantic_digest` / `presentation_digest`,
+  `change_kind`, `diff`, and `policy_record()` (the versioned `.policy.json` envelope —
+  see `docs/policy-artifact-contract.md`, the authoritative copy of the contract).
+- `statespec.render` — Mermaid, tables, and the generated lifecycle doc.
+
+Pure Python, stdlib-only, no dependencies.
+
+## Quick start
+
+```bash
+pip install statespec
+```
+
+```python
+from statespec import StateSpec, Transition, apply, validate
+from statespec.expr import field
+
+spec = StateSpec(
+    name="review", title="Review",
+    states={"draft": "Being written", "submitted": "Awaiting review",
+            "approved": "Done"},
+    fields={"amount": "int"},
+    initial="draft", terminal=frozenset({"approved"}),
+    transitions=(
+        Transition("submit", ("draft",), "submitted",
+                   roles=frozenset({"author"})),
+        Transition("approve", ("submitted",), "approved",
+                   roles=frozenset({"reviewer"}),
+                   guard=field("amount").le(100)),
+    ),
+)
+
+assert validate(spec, known_roles=frozenset({"author", "reviewer"})) == []
+apply(spec, "approve", "submitted", frozenset({"reviewer"}), {"amount": 40})
+# -> "approved". Wrong role -> PermissionDenied; amount 500 -> GuardRejected;
+# fire() returns the same decision plus structured evidence per condition.
+```
+
+Every claim above is exercised by the test suite: the refusal taxonomy and
+its precedence in `tests/test_core.py`, the expression grammar and
+typechecking in `tests/test_expr.py`, digests/diff in `tests/test_identity.py`,
+and canonicalisation byte-stability against a golden artifact in
+`tests/test_contract_golden.py`.
+
+## Boundaries (what this does not do)
+
+statespec sits *above* concurrency and persistence. It decides whether a
+transition is legal; it does not make the write atomic or durable. It will
+not stop a race between two concurrent transitions (pair it with optimistic
+locking or a version column at the persistence layer), a forgotten lock, an
+out-of-band mutation that sets `status` around the interpreter, or a
+cross-system inconsistency. The "single enforcement path" property holds
+only if every status write in the application routes through `apply`/`fire`
+— enforce that with a repo-level convention or CI gate, not by trust. The
+digests identify *policy* change; they do not verify that deployed code
+matches the artifact — that check belongs to CI or a control plane.
+
+## Provenance
+
+Extracted from [`ConceptPending/baseplate`](https://github.com/ConceptPending/baseplate)
+branch `example/state-machine` at tag `statespec-v0.3.0` (commit `2aca24e`, 2026-06-10),
+where the kernel was developed and frozen. The only changes at extraction were the import
+rename `app.statespec` → `statespec` and doc-path adjustments. This repository is the
+kernel's authoritative home from `statespec-v0.4.0` onward; the in-tree copy in baseplate
+remains frozen at v0.3.0 as part of the reference example.
+
+## Versioning and freeze discipline
+
+Kernel tags form their own series (`statespec-vX.Y.Z`), separate from any consuming
+product's versions. The canonicalisation and digest rules are a **frozen contract**:
+any change to the policy-artifact envelope bumps `schema_version` and the kernel tag
+together, and is recorded in `docs/policy-artifact-contract.md`'s changelog. Changes
+that alter existing digests are breaking and require explicit re-binding by consumers
+(e.g. approval planes). Exceptions to the freeze: genuine bugs, security issues, or
+contract defects.
+
+Known consumers: `baseplate` (reference example, v0.3.0), `baseplate-control`
+(approval plane; vendors this kernel byte-identically and verifies digests independently).
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+.venv/bin/ruff check src tests
+```

statespec-0.4.0/docs/policy-artifact-contract.md

@@ -0,0 +1,131 @@
+# The policy artifact: a versioned contract
+
+**Authoritative home:** this repository (`ConceptPending/statespec`) as of
+`statespec-v0.4.0`. The copy in `baseplate` is frozen at v0.3.0 alongside its
+reference example.
+
+**Changelog:**
+
+- `statespec-v0.3.0` (2026-06-10, baseplate `2aca24e`) — kernel freeze;
+  envelope `schema_version: 2` (`semantic_digest` + `presentation_digest`).
+- `statespec-v0.4.0` (2026-07-03, this repo) — `spec` gains `title`. Both
+  digests and `schema_version: 2` are **unchanged** (`title` never enters the
+  semantic projection; the presentation projection already hashed it). Fixes a
+  contract defect found while integrating the control plane: previously
+  `presentation_digest` hashed `spec.title` but the artifact omitted it, so the
+  digest was not independently verifiable and `diff()` could not describe a
+  title change. Consumers may now verify `presentation_digest` from the
+  artifact alone whenever `"title" in spec`.
+
+**Freeze discipline:** changes are limited to genuine bugs, security issues, or
+contract defects. The next envelope change bumps `schema_version` and the
+kernel tag together.
+
+In a consuming repo, `make spec-doc` (or equivalent) writes
+`docs/specs/<name>.policy.json` for every lifecycle spec.
+This file is the **stable, machine-readable contract** an external consumer (a
+control plane, a policy-review GitHub App, an auditor tool) reads. This document
+defines it so that contract can be relied on across repos and over time.
+
+## Status of the artifact
+
+It is a **committed / declared baseline** — the policy the repository currently
+declares. It is **not** an *approved* policy. Approval is an independent record
+(who authorised which `semantic_digest`, when) that lives in the control plane,
+never in the repository. A repo can change the spec and its `.policy.json` in one commit;
+that makes it the *candidate* policy, not the *authorised* one.
+
+## Shape (schema_version 2)
+
+```jsonc
+{
+  "schema_version": 2,                  // version of THIS envelope format (not the policy)
+  "spec_version": 1,                    // the author-asserted policy version
+  "semantic_digest": "c90feaf9c431…",   // sha256 over executable behaviour — what approval binds to
+  "presentation_digest": "a5765188d595…", // sha256 over wording — tracked, non-invalidating
+  "spec": {                             // the canonical, content-only spec
+    "name": "submission",
+    "title": "Submission moderation",   // added in v0.4.0 (presentation; not in the semantic hash)
+    "version": 1,
+    "states": { "pending": "…", "approved": "…", … },
+    "initial": "pending",
+    "terminal": ["approved", "rejected", "expired"],
+    "fields": { "status": "str", "age_days": "decimal" },
+    "transitions": [
+      {
+        "id": "approve",                 // control_id, else the action name
+        "name": "approve",
+        "from": ["pending"], "to": "approved",
+        "roles": ["reviewer"],
+        "label": "…",
+        "guard": { "kind": "compare", "op": "eq",
+                   "left": {"kind":"field","name":"error_count"},
+                   "right": {"kind":"literal","type":"int","value":0} },
+        "opaque": {}                     // {name:version -> source-hash} for opaque guards
+      }
+    ],
+    "invariants": [
+      { "id": "status_declared", "name": "status_declared", "label": "…",
+        "condition": { … expr tree … }, "opaque": {} }
+    ]
+  }
+}
+```
+
+## Guarantees the contract makes
+
+- **Two digests, both deterministic and content-only.** Each is `sha256` over a
+  canonical serialisation (sorted keys, stable arrays, normalised `Decimal`).
+  `semantic_digest` covers **executable behaviour** — states, transitions,
+  roles, guard/invariant expressions, and **opaque-body** hashes; it is what
+  approval binds to, and bumping `spec_version` is keyed to it. `presentation_digest`
+  covers the **human-facing wording** — title, state descriptions, and
+  transition/invariant labels. A copy-edit moves `presentation_digest` only, so
+  a behavioural approval survives a reword; a behavioural change moves
+  `semantic_digest` (and almost always both). Splitting them is what makes
+  "wording vs behaviour" a mechanical check (`identity.change_kind`) instead of
+  a human judgement on every diff.
+- **Conditions are data, not code.** `guard`/`condition` are expression trees
+  (compare + boolean), so a consumer can render, diff, and reason about them
+  without executing the application. The grammar is closed (see
+  `statespec-expressions.md`).
+- **Opaque code is identified, not hidden.** A guard that escapes to Python
+  appears as `{"kind":"opaque","name":…,"version":…}` and its source hash is in
+  the transition/invariant's `opaque` map, so an opaque body change is visible
+  in the digest.
+- **Control IDs are stable.** Each transition/invariant carries an `id`
+  (`control_id`, defaulting to the name) — the handle a control plane maps to an
+  owner and an approval requirement. It survives a label reword.
+
+## What a consumer should do, not do
+
+- **Do**: read the artifact, compute/compare digests, diff two artifacts
+  semantically (see `identity.diff`), map `control_id`s to owners, and gate on
+  GitHub events.
+- **Don't**: parse the application's models, import its code, or re-run the
+  guard functions. The artifact + GitHub events are sufficient.
+
+## Versioning
+
+- `schema_version` versions the **envelope/format**. Bump it only when this
+  shape changes; a consumer keys its parser off it.
+- `spec_version` is the **policy's** author-asserted version. Bump it when the
+  **`semantic_digest`** changes. `identity.diff` names the change; consuming
+  repos typically add a CI check that warns when the semantic digest changed
+  but the version did not (baseplate's `scripts/statespec.py diff` is the
+  reference). A wording-only change does not require a bump.
+- The two are independent: a format migration doesn't touch policy versions, and
+  a policy change doesn't touch the format version.
+
+## Note on labels (the semantic/presentation split)
+
+`spec` still includes labels/descriptions in full — a reword is never lost. But
+identity is split: a reword moves `presentation_digest` only, leaving
+`semantic_digest` (the digest approval binds to) untouched. So an editorial
+change is **non-invalidating by default** — `diff` still names it ("transition
+X: label changed") and a consumer routes it to the general policy owner for a
+lightweight ack, rather than re-triggering control-owner approval. This was a
+deliberate pre-v1 split, made while there were zero live approval bindings to
+migrate; doing it after the control plane accumulated approvals would have been
+a breaking re-binding. Mechanically: compare the two records with
+`identity.change_kind` → `semantic` | `presentation` | `none`.