statifier 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9bdfc97800bff6f64deb8fb099939d0accfdfb8f7a9e7652ad55d4e2ca29e8c
-  data.tar.gz: 80c24b848b4af687d106b48ae0f77cf2ce8bc68ef00fc21446719a20012635c2
+  metadata.gz: cebbdd45b781d52f2f9b925b1c8b06c7cd321758bc0adf35ca344160b70161dd
+  data.tar.gz: d40888ba1fe414cb952554dc9633f36bd1c12dba0643229d339e6904e0ed64f4
 SHA512:
-  metadata.gz: e60f13e1f4cf54ff26e7c20e2c1810e35fe914c70fec7a4eb6c5d25f5401ea9a5653559341e953106296e7f285e9deedc579adc5e4ef4ac5d997db697577390a
-  data.tar.gz: a90dbdd55e43a2b1d9bd74b1f1f86b64f86687db48fb2dd216c16d35e7443bbd1a91fccaf40812867966befe288f99bab069718948dc0ec153fea093ffc6c9c7
+  metadata.gz: 0bef4c0dc4e70485c8c33cf2256e62c76cac63af40d346b404057a146f174ecb47121ea3a4065d19b259e6a2ffcf6390f4f9496f4fc3b59a5dc8e70ef69f32fd
+  data.tar.gz: 5fc9d39c0ba0f32286aba0a2c0f1ce14744ee431793f27fc7a10ace68bd6fa4241dac3dc52301fddf918dca314245672698afbbe63381dbcbe7420e54e023d2e

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+### Upcoming
+
+### 0.1.0 / 2026-10-24
+
+The first release of the rewrite, which replaces the 0.0.1 stub of 2019 that carried no statechart code. `statifier` is the interpreter core of an SCXML statechart engine for Ruby 3.3 and later: a step takes an immutable state and an event and answers a new state and plain-data effects, with no process, real clock or I/O of its own. It has one runtime dependency, `predicator` (`>= 2.0`, `< 3`). It is held to the conformance corpus of statifier-ex at the tag `v2.16.0` (corpus hash `sha256:7440f9a34a84b0657cb3bde11f96cf1707db08fb05e202c1e0249ab965517cc8`) and claims 320 of its cases under four claims: `scion`, `statifier`, `w3c-mandatory` and `w3c-optional`. The registry lists the claimed cases and the gate fails when one does not pass.
+
+**Added**
+
+* `Statifier.compile(source)` compiles an SCXML document into a frozen machine and answers a result: `ok?`, the machine as `value`, or as `error` the list of refusals from the first stage that refused (the XML reader, the lowering, the validator, or the compiler when predicator refuses an expression). A validator warning never refuses; the machine carries it.
+* `Statifier.start(machine, **options)` starts a compiled chart and answers a result whose `value` is the chart's state, an immutable value, and the effects the start made; the options are `session_id:` (minted as `sess_` and 26 base32 symbols when absent), `datamodel:`, `processors:`, `max_macrostep_rounds:`, `trace:` and `clock:`.
+* `Statifier.step(state, name, data:)` sends the chart one external event and runs it to a stable configuration; it answers the error `:not_running` once the chart has stopped.
+* `Statifier.advance(state, milliseconds)` moves the chart's virtual clock forward and fires every delayed send due by then, earliest first; it answers the error `:invalid_duration` for a negative or non-finite duration.
+* `Statifier.configuration(state)` answers the active states by id, and `Statifier.done?(state)` whether the chart has stopped, with its donedata and the states it stopped in.
+* A send of a type a host registers is handed to the host's processor for that type, passed with every call: its `deliver(send, event, context)`, its `cancel(cancel, context)` for a delayed send it holds, and its `ioprocessors_entry(type, context)` for `_ioprocessors`.
+* A host reads the validator's warnings on the compiled machine, `machine.warnings`.
+* An `<invoke>` of the SCXML type with inline `<content>` markup runs as an in-process child session: `Statifier.start`, `Statifier.step` and `Statifier.advance` start it, deliver to it, forward to it when the invocation sets `autoforward`, fire its timers on the same virtual clock, return its `done.invoke.<id>` with its donedata, and cancel it, running its `<onexit>` handlers, when the invoking state exits. Its session id is its parent's, a dot and the invoke id; it inherits its parent's registered send types and trace flag; `#_parent` and `#_<invokeid>` reach between the two, and `idlocation`, `namelist`, `<param>` and `<finalize>` work as the specification says.
+* The effects a call answers carry the invocation effects `Statifier::Effect::Invoke`, `Statifier::Effect::CancelInvoke` and `Statifier::Effect::Autoforward`, and every effect an invoked child's execution answers, wrapped in a `Statifier::Effect::Child` that names the child's session id.
+* `Statifier.export_position(state)` writes a chart's execution out as a position: a frozen Hash with String keys in the reference's string-id vocabulary (the configuration, the entered states, the states to invoke, the recorded history, the live invocations, the counters, the datamodel with each value as tagged-value text, and the running flag and status), ready for JSON. It refuses a state whose internal queue holds an event, a state holding a state with no id, and a datamodel value the tagged-value encoding has no form for.
+* `Statifier.import_position(machine, position, processors: {})` reads a position back in as a driver state over `machine`. It refuses a value that is not a position (`:malformed_export`) and ids `machine` holds no state for (`:unknown_state_ids`); the virtual clock, pending timers and queued events start empty, as a position does not carry them.
+* `Statifier.report_send_failed(machine, state, send, **options)` reports a send the host was handed and could not deliver: the chart takes `error.communication`, its `sendid` the send's id whether or not the author named it, and runs to a stable configuration; the options are `reason:` (not read), `processors:` and `clock:`. It answers the error `:not_running` once the chart has stopped and `:halted` while a round budget has halted it.
+* A processor's `deliver` may answer `Statifier::Driver::DeliveryFailure.new(reason:)` for a send it cannot deliver, and the chart takes the same `error.communication` within the call that handed the send.
+* `Statifier.check_accepts(machine, declared_events)` compares the event names a host declares a chart accepts with the event descriptors the chart listens for on the transitions of every state some path can enter, matched as transition selection matches an event, and answers a frozen `Statifier::AcceptsCheck`: `unreachable`, the declared names no descriptor matches, in the declaration's order; and `undeclared`, the descriptors that match no declared name, in transition order (a state's own transitions before its children's). With `nil` for the declaration both lists are empty; it refuses nothing.
+* `require "statifier/basichttp"` loads the HTTP transport, the seam a Basic HTTP processor makes its requests through; `require "statifier"` alone loads none of it and no HTTP library.
+* A transport is any callable that takes a `Statifier::BasicHTTP::Request` (`http_method`, `url`, `headers`, `body`) and answers a `Statifier::BasicHTTP::Response` (`status`, `headers`, `body`), whatever its status, or raises `Statifier::BasicHTTP::TransportError` when no response came back; both values are frozen, and building one copies a string it is given that is not already frozen.
+* `Statifier::BasicHTTP::NetHTTPTransport` is the default transport, on the standard library's Net::HTTP: one attempt per call, each step bounded by `timeout:` seconds (five when absent), and `connect:` for a host's own Net::HTTP connection.
+* `Statifier::BasicHTTP::Processor`, loaded by `require "statifier/basichttp"`, is the Basic HTTP Event I/O Processor: built with `base_url:`, `report:` and an optional `transport:`, its `send_types` register it under `Statifier::BasicHTTP::EVENT_PROCESSOR` and `basichttp`, and a session's `_ioprocessors` then carries its location, the base URL, `/` and the session's id, under both.
+* Each send the processor is handed becomes one POST through the transport: a Hash of data as form fields beside `_scxmleventname`, no data as `_scxmleventname` alone, any other value as a `text/plain` body with the event name in the query string, every request carrying the send's `scxml-send-key` header.
+* A send with no target fails within the call as `error.communication`; a status outside 2xx, a transport error, a target that is not a String and a delayed send are handed to `report:` as a `Statifier::BasicHTTP::Failure`, for the host to pass to `Statifier.report_send_failed` once the call returns.
+* `Statifier::BasicHTTP.decode(method:, content_type:, body:, query:, send_key:)` turns a request a host's server took into the external event it carries, or a `Statifier::BasicHTTP::Refusal` (`:method_not_allowed`, `:not_utf8`, `:malformed_send_key`).
+
+**Changed**
+
+* An `<invoke>` whose type is not the SCXML type now raises `error.execution`, and one with no content, content that is not markup or markup that does not compile raises `error.communication`; `src` is never fetched.
+* Every constant outside the public surface is now private (`private_constant`), so a host cannot name it. What a host may use: the ten calls on `Statifier` (`compile`, `start`, `step`, `advance`, `report_send_failed`, `configuration`, `done?`, `export_position`, `import_position`, `check_accepts`); `Statifier::Result`, `Statifier::AcceptsCheck`, `Statifier::Event` and its `Cause`, every value under `Statifier::Effect` and `Statifier::Effect::Trace`, `Statifier::Driver::Moved`, `DoneStatus`, `Context` and `DeliveryFailure`, `Statifier::Position::KEYS` and `Statifier::Position::Refusal`, and `Statifier::VERSION`; and, after `require "statifier/basichttp"`, `Statifier::BasicHTTP.decode`, `EVENT_PROCESSOR`, `SHORT_TYPE`, `Processor`, `Failure`, `Refusal`, `Request`, `Response`, `TransportError` and `NetHTTPTransport`.
+* The machine, a driver state and the refusals `Statifier.compile` answers are read by their documented members; their classes are private.

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 JohnnyT
+Copyright (c) 2019-2026 JohnnyT
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal