Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 3 additions & 28 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,34 +21,6 @@ jobs:
- name: Check out tutorial
uses: actions/checkout@v7

- name: Check out specification
uses: actions/checkout@v7
with:
repository: fruwehq/determa-state-spec
ref: c1635d74e6a216301a8986d37be8ce7e7111dfd7
path: .sources/determa-state-spec

- name: Check out conformance
uses: actions/checkout@v7
with:
repository: fruwehq/determa-state-conformance
ref: 600523ca08c3b8a6ee790439a32dc4ce47f71b95
path: .sources/determa-state-conformance

- name: Check out Python engine
uses: actions/checkout@v7
with:
repository: fruwehq/determa-state-python
ref: 7b17d788b48049648e7e463aa3d35ba13dc1aa6e
path: .sources/determa-state-python

- name: Check out Rust engine
uses: actions/checkout@v7
with:
repository: fruwehq/determa-state-rust
ref: d17480c8b281dcd17953f59afcf6b5d23ff44efd
path: .sources/determa-state-rust

- name: Set up Python
uses: actions/setup-python@v7
with:
Expand All @@ -63,6 +35,9 @@ jobs:
- name: Install pinned dependencies
run: python -m pip install --requirement requirements.txt

- name: Fetch pinned Determa State sources
run: make sources

- name: Validate released version is current
env:
GITHUB_TOKEN: ${{ github.token }}
Expand Down
13 changes: 7 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,13 @@ and applicable `determa-state-conformance` core cases decide portable behavior.

## Current target

- Determa State synchronized version: `0.1.0`
- Determa State synchronized version: `0.2.0`
- machine grammar: numeric `format: 1`
- exact source revisions: `sources.lock.yaml`

The coverage matrix must contain every normative specification section and every
actual core conformance case at the pinned revisions.
The coverage matrix must contain every normative specification section, every actual
core conformance case, and every released execution-checkpoint profile case directory
at the pinned revisions.

## Working rules

Expand Down Expand Up @@ -50,8 +51,8 @@ actual core conformance case at the pinned revisions.
name an existing chapter. Planned entries must name an open implementation issue.
- Normative text belongs in `determa-state-spec`, not here. Link to it and explain it
in beginner language.
- Persistence/migration content is released in State 0.1.0 and tracked for tutorial
implementation by issue #7.
- Persistence, migration, and execution-checkpoint hosting are released in State 0.2.0
and taught in the corresponding guides.
- Package-import content remains unsupported until a portable import contract exists.

## Gates
Expand All @@ -68,7 +69,7 @@ strict site-build validation. CI is the same contract.
## Repository map

- `docs/`: authored tutorial chapters.
- `coverage.yaml`: spec-section and core-case disposition.
- `coverage.yaml`: spec-section, core-case, and released profile-case disposition.
- `sources.lock.yaml`: immutable upstream source identities.
- `STATE_VERSION`: synchronized State version displayed and checked.
- `scripts/`: extraction and validation tools.
Expand Down
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ same extracted machine and assert the same observable trace.

## Update coverage

Every pinned normative section and core conformance case has exactly one entry in
`coverage.yaml`.
Every pinned normative section, core conformance case, and released
execution-checkpoint profile case directory has exactly one entry in `coverage.yaml`.

- `covered`: an existing chapter demonstrably explains or executes the item.
- `planned`: the item is assigned to an existing chapter path and open child issue.
Expand Down
23 changes: 12 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
The manual, beginner-friendly tutorial, and documentation website for
[Determa State](https://github.com/fruwehq/determa-state-spec).

The tutorials currently target synchronized Determa State **0.1.0** and the numeric
The tutorials currently target synchronized Determa State **0.2.0** and the numeric
`format: 1` grammar. Start with
[Your first machine](docs/getting-started/first-machine.md).

Expand All @@ -18,8 +18,8 @@ Every chapter is ordinary Markdown:
are never maintained as duplicate authored copies.

This repository explains and demonstrates Determa State. The
[specification](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md) and
[conformance suite](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0)
[specification](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md) and
[conformance suite](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0)
remain normative.

Independent, fully working real-world applications live in
Expand All @@ -37,22 +37,23 @@ make sources
make check
```

`make check` verifies the pinned source versions, coverage totality, YAML 1.2 parsing,
JSON Schema validity, Python and Rust traces, and the strict MkDocs build.
`make check` verifies the pinned source versions, specification/core/profile coverage
totality, YAML 1.2 parsing, JSON Schema validity, Python and Rust traces, and the strict
MkDocs build.

Use `make serve` to preview the site locally.

## Status

The released format-1 user-facing surface is taught and executed across the progressive
guides. The machine-readable [`coverage.yaml`](coverage.yaml) inventories every
normative section and core conformance case as covered or deliberately
non-user-facing.
normative section, core conformance case, and released execution-checkpoint profile
case as covered or deliberately non-user-facing.

Persistence and definition migration include a beginner SQLite walkthrough and an
advanced 105-vector Python/Rust reference lab. Aggregate packages are supported as
content-addressed transport; portable package imports in machine definitions remain
unsupported.
Persistence and definition migration include a durable execution-checkpoint tutorial,
a lower-level SQLite transaction walkthrough, and an advanced 108-vector Python/Rust
reference lab. Aggregate packages are supported as content-addressed transport;
portable package imports in machine definitions remain unsupported.

See [CONTRIBUTING.md](CONTRIBUTING.md) before changing examples or coverage.

Expand Down
2 changes: 1 addition & 1 deletion STATE_VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.1.0
0.2.0
23 changes: 22 additions & 1 deletion coverage.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
state_version: "0.1.0"
state_version: "0.2.0"

specification:
- id: "0"
Expand Down Expand Up @@ -151,6 +151,21 @@ specification:
- { id: "16.12", status: covered, chapter: docs/guides/persistence-migration-reference.md }
- { id: "16.13", status: covered, chapter: docs/guides/persistence-migration-reference.md }
- { id: "16.14", status: covered, chapter: docs/guides/persistence-migration-reference.md }
- { id: "17", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.1", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.2", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.3", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.4", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.5", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.6", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.7", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.8", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.9", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.10", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.11", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.12", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.13", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { id: "17.14", status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }

conformance:
- { case: 01-guarded-leaf, status: covered, chapter: docs/getting-started/first-machine.md }
Expand Down Expand Up @@ -263,3 +278,9 @@ conformance:
- { case: 113-migration-failure-completeness, status: covered, chapter: docs/guides/persistence-migration-reference.md }
- { case: 114-occurrence-local-transform-binding, status: covered, chapter: docs/guides/persistence-migration-reference.md }
- { case: 115-target-identity-decimal-projections, status: covered, chapter: docs/guides/persistence-migration-reference.md }
- { case: 116-legacy-format-policy, status: covered, chapter: docs/guides/core-statecharts.md }

execution_checkpoint_profile:
- { case: checkpoint-01-delivery-lifecycle, status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { case: checkpoint-02-outbox-lifecycle, status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
- { case: checkpoint-03-retention-and-root-lifecycle, status: covered, chapter: docs/guides/execution-checkpoint-hosting.md }
12 changes: 6 additions & 6 deletions docs/getting-started/first-machine.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ type errors before the machine runs.
Install the released engine:

```sh
python -m pip install determa-state==0.1.0
python -m pip install determa-state==0.2.0
```

The complete program is below. `create` returns the initial state. `dispatch` returns
Expand Down Expand Up @@ -146,12 +146,12 @@ Create a small Cargo project with the released crate.
```toml
[package]
name = "determa-first-counter"
version = "0.1.0"
version = "0.2.0"
edition = "2021"
publish = false

[dependencies]
determa-state = "=0.1.0"
determa-state = "=0.2.0"
```

The Rust program uses the same machine file and asserts the same count and
Expand Down Expand Up @@ -228,7 +228,7 @@ The [coverage status](../reference/coverage.md) maps the complete released forma
surface.

Normative references:
[bundle grammar §4](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#4-bundle-grammar),
[CEL §5](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#5-static-validation-and-cel),
[bundle grammar §4](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#4-bundle-grammar),
[CEL §5](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#5-static-validation-and-cel),
and
[dispatch §6](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#6-event-and-transition-semantics).
[dispatch §6](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#6-event-and-transition-semantics).
44 changes: 22 additions & 22 deletions docs/guides/cel-and-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Determa State uses [CEL](https://cel.dev/) for guards and computed action values
The machine file remains data: the engine parses and type-checks every expression when
the bundle loads, then evaluates only the expressions selected by an event.

This chapter uses the closed portable CEL profile from Determa State 0.1.0. It does not
This chapter uses the closed portable CEL profile from Determa State 0.2.0. It does not
use host functions or implementation-specific CEL extensions.

## Start with ordered guards
Expand Down Expand Up @@ -607,7 +607,7 @@ and a root fault is terminal.
Install the pinned engine:

```sh
python -m pip install determa-state==0.1.0
python -m pip install determa-state==0.2.0
```

<!-- determa-example: python/cel_actions.py -->
Expand Down Expand Up @@ -887,12 +887,12 @@ print(f"guards=standard,bulk,empty; total=4.5; audit={audit_summary}; faults=11"
```toml
[package]
name = "determa-cel-actions"
version = "0.1.0"
version = "0.2.0"
edition = "2021"
publish = false

[dependencies]
determa-state = "=0.1.0"
determa-state = "=0.2.0"
```

<!-- determa-example: rust/cel-actions/src/main.rs -->
Expand Down Expand Up @@ -1302,24 +1302,24 @@ language traces. The code above is the tested source, not pseudocode.
## Coverage

This chapter covers the format-1 structured-action and CEL rules linked below. The
matching Determa State v0.1.0 conformance cases are:

- [12 guarded list](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/12-guarded-list)
- [17 action fault](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/17-action-fault)
- [61 expression map order](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/61-expression-map-order)
- [64 dynamic target expression order](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/64-dynamic-target-expression-order)
- [65 portable CEL profile](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/65-portable-cel-profile)
- [66 CEL profile rejections](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/66-cel-profile-rejections)
- [68 CEL AND non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/68-cel-and-nonabsorbed-error)
- [69 CEL OR non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/69-cel-or-nonabsorbed-error)
- [70 dynamic target list order](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/70-dynamic-target-list-order)
- [71 reversed CEL AND non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/71-cel-reversed-and-nonabsorbed-error)
- [72 reversed CEL OR non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/72-cel-reversed-or-nonabsorbed-error)
- [79 missing refresh field](https://github.com/fruwehq/determa-state-conformance/tree/v0.1.0/conformance/core/79-missing-refresh-field)
matching Determa State v0.2.0 conformance cases are:

- [12 guarded list](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/12-guarded-list)
- [17 action fault](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/17-action-fault)
- [61 expression map order](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/61-expression-map-order)
- [64 dynamic target expression order](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/64-dynamic-target-expression-order)
- [65 portable CEL profile](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/65-portable-cel-profile)
- [66 CEL profile rejections](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/66-cel-profile-rejections)
- [68 CEL AND non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/68-cel-and-nonabsorbed-error)
- [69 CEL OR non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/69-cel-or-nonabsorbed-error)
- [70 dynamic target list order](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/70-dynamic-target-list-order)
- [71 reversed CEL AND non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/71-cel-reversed-and-nonabsorbed-error)
- [72 reversed CEL OR non-absorbed error](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/72-cel-reversed-or-nonabsorbed-error)
- [79 missing refresh field](https://github.com/fruwehq/determa-state-conformance/tree/v0.2.0/conformance/core/79-missing-refresh-field)

Normative references:
[structured actions §4.8](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#48-structured-actions),
[static validation and CEL §5](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#5-static-validation-and-cel),
[portable CEL profile](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#portable-cel-profile),
[structured actions §4.8](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#48-structured-actions),
[static validation and CEL §5](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#5-static-validation-and-cel),
[portable CEL profile](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#portable-cel-profile),
and
[faults §10](https://github.com/fruwehq/determa-state-spec/blob/v0.1.0/SPEC.md#10-faults-and-envelope-disposition).
[faults §10](https://github.com/fruwehq/determa-state-spec/blob/v0.2.0/SPEC.md#10-faults-and-envelope-disposition).
Loading