procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/tests/test_put_projects.py

@@ -0,0 +1,41 @@
+"""put-projects: empty-body echo hardening (O4) — warns that an empty success can lie."""
+from __future__ import annotations
+
+from tools.procesio import main
+from tools.procesio.client import ProcesioClient
+from tools.procesio.tests.conftest import FakeResp, FakeSession
+
+
+def _builder(session):
+    return lambda prof: ProcesioClient(
+        profile={"type": "apikey", "key": "N", "value": "V"}, name="t", session=session)
+
+
+def test_empty_body_put_warns_and_reports_meta():
+    # 200 with an empty body -> _parse_body yields {"raw_text": ""} (the O4 shape).
+    sess = FakeSession(queue=[FakeResp(200, None, text="")])
+    out = main.dispatch("put-projects", ["--body", '{"id": "X", "name": "n"}'],
+                        client_builder=_builder(sess))
+    assert "warning" in out
+    assert "empty" in out["warning"].lower() and "verify" in out["warning"].lower()
+    assert out["http"]["status"] == 200
+    assert out["http"]["body_len"] == 0
+
+
+def test_non_empty_body_put_has_no_warning():
+    body_text = '{"id": "X"}'
+    sess = FakeSession(queue=[FakeResp(200, {"id": "X"}, text=body_text)])
+    out = main.dispatch("put-projects", ["--body", '{"id": "X"}'],
+                        client_builder=_builder(sess))
+    assert "warning" not in out
+    assert out["http"]["status"] == 200
+    assert out["http"]["body_len"] == len(body_text)
+
+
+def test_put_projects_dry_run_composes_without_sending():
+    sess = FakeSession()
+    out = main.dispatch("put-projects", ["--body", '{"id": "X"}', "--dry-run"],
+                        client_builder=_builder(sess))
+    assert out["dry_run"] is True
+    assert out["method"] == "PUT" and out["path"] == "/api/Projects"
+    assert sess.calls == []

procesio_cli/tools/procesio/tests/test_reliability.py

@@ -0,0 +1,107 @@
+"""Unit tests for the request-reliability primitives (offline, no HTTP)."""
+from __future__ import annotations
+
+import random
+import time
+
+import pytest
+
+from tools.procesio import reliability
+
+
+# -- deadline resolution ----------------------------------------------------
+
+def test_resolve_deadline_class_defaults():
+    assert reliability.resolve_deadline("GET", reliability.DEFAULT) == reliability.READ_DEADLINE
+    assert reliability.resolve_deadline("PUT", reliability.DEFAULT) == reliability.WRITE_DEADLINE
+    assert reliability.resolve_deadline("POST", reliability.DEFAULT) == reliability.WRITE_DEADLINE
+
+
+def test_resolve_deadline_none_is_exempt():
+    assert reliability.resolve_deadline("GET", None) is None
+
+
+def test_resolve_deadline_numeric_override():
+    assert reliability.resolve_deadline("GET", 5) == 5.0
+
+
+def test_resolve_deadline_env_optout(monkeypatch):
+    monkeypatch.setenv(reliability.ENV_NO_DEADLINE, "1")
+    assert reliability.resolve_deadline("GET", reliability.DEFAULT) is None
+    assert reliability.resolve_deadline("PUT", 30) is None
+
+
+# -- retry policy -----------------------------------------------------------
+
+def test_is_retryable_get_only_transient():
+    assert reliability.is_retryable("GET", 503, 0) is True
+    assert reliability.is_retryable("GET", 429, 0) is True
+    # 500 is deliberately excluded (may be deterministic, not transient)
+    assert reliability.is_retryable("GET", 500, 0) is False
+    # writes are NEVER retryable — the single structural guarantee
+    assert reliability.is_retryable("POST", 503, 0) is False
+    assert reliability.is_retryable("PUT", 503, 0) is False
+
+
+def test_is_retryable_respects_attempt_budget():
+    assert reliability.is_retryable("GET", 503, reliability.MAX_RETRIES) is False
+
+
+def test_retry_env_optout(monkeypatch):
+    monkeypatch.setenv(reliability.ENV_NO_RETRY, "true")
+    assert reliability.is_retryable("GET", 503, 0) is False
+    assert reliability.network_error_retryable("GET", 0) is False
+
+
+def test_network_error_retryable_get_only():
+    assert reliability.network_error_retryable("GET", 0) is True
+    assert reliability.network_error_retryable("POST", 0) is False
+
+
+def test_full_jitter_within_bounds():
+    rng = random.Random(1234)
+    for attempt in range(1, 12):
+        ceiling = min(reliability.BACKOFF_CAP, reliability.BACKOFF_BASE * (2 ** attempt))
+        v = reliability.full_jitter(attempt, rng)
+        assert 0.0 <= v <= ceiling
+    # large attempt is capped
+    assert reliability.full_jitter(20, rng) <= reliability.BACKOFF_CAP
+
+
+def test_parse_retry_after():
+    assert reliability.parse_retry_after({"Retry-After": "3"}) == 3.0
+    assert reliability.parse_retry_after({"retry-after": "2"}) == 2.0  # case-insensitive
+    assert reliability.parse_retry_after({"Retry-After": "999"}) == reliability.BACKOFF_CAP
+    assert reliability.parse_retry_after({"Retry-After": "Wed, 21 Oct"}) is None  # HTTP-date ignored
+    assert reliability.parse_retry_after({}) is None
+    assert reliability.parse_retry_after(None) is None
+
+
+# -- total deadline ---------------------------------------------------------
+
+def test_run_with_deadline_returns_value():
+    assert reliability.run_with_deadline(lambda: 42, 1.0) == 42
+
+
+def test_run_with_deadline_no_deadline_runs_inline():
+    assert reliability.run_with_deadline(lambda: "ok", None) == "ok"
+
+
+def test_run_with_deadline_trips_on_slow_fn():
+    def slow():
+        time.sleep(1.0)
+        return "late"
+    with pytest.raises(reliability.DeadlineHit):
+        reliability.run_with_deadline(slow, 0.1)
+
+
+def test_run_with_deadline_reraises_worker_exception():
+    def boom():
+        raise ValueError("kaboom")
+    with pytest.raises(ValueError, match="kaboom"):
+        reliability.run_with_deadline(boom, 1.0)
+
+
+def test_run_with_deadline_zero_timeout_trips_immediately():
+    with pytest.raises(reliability.DeadlineHit):
+        reliability.run_with_deadline(lambda: 1, 0)

procesio_cli/tools/procesio/tests/test_removal_gate.py

@@ -0,0 +1,95 @@
+"""The removal gate: a desired-state save may not silently delete what it omits.
+
+Why this exists. `process-edit --config` replaces the definition, so anything the config
+leaves out is removed, and the payload cannot say whether that was meant: a config with 4
+actions against a live flow of 13 looks identical whether the author intended to drop 9 or
+had lost track of the flow. Neither existing guard catches it — the validation gate asks
+whether the RESULT is valid (a truncated flow usually still is), and `PUT /api/Projects`
+persists even when it answers HTTP 400 (by design: unfinished work must be saveable).
+
+Seen live: an incomplete write cut a 13-action flow to 2, and the next step — reading that
+state and rebuilding from a partial picture — dropped 8 more variables. So the gate does not
+judge the removal; it makes the consequence visible before it is paid and asks for intent.
+"""
+from __future__ import annotations
+
+import pytest
+
+from tools.procesio.dto.process.builder import _removal_gate
+from tools.procesio.errors import RemovalBlocked
+
+
+def _live(actions=(), variables=()):
+    return {"_live_flow": {
+        "actions": [{"name": n} for n in actions],
+        "variables": [{"name": n} for n in variables],
+    }}
+
+
+def _dto(actions=(), variables=()):
+    return {"Actions": [{"Name": n} for n in actions],
+            "Variables": [{"Name": n} for n in variables]}
+
+
+def test_keeping_everything_passes():
+    _removal_gate(_dto(["Start", "Trim", "Stop"], ["a", "b"]),
+                  _live(["Start", "Trim", "Stop"], ["a", "b"]))
+
+
+def test_adding_is_never_a_removal():
+    _removal_gate(_dto(["Start", "Trim", "To Upper", "Stop"], ["a", "b", "c"]),
+                  _live(["Start", "Trim", "Stop"], ["a", "b"]))
+
+
+def test_dropping_an_action_is_refused():
+    with pytest.raises(RemovalBlocked) as e:
+        _removal_gate(_dto(["Start", "Stop"]), _live(["Start", "Trim", "Stop"]))
+    assert e.value.removed["actions"] == ["Trim"]
+
+
+def test_dropping_a_variable_is_refused():
+    with pytest.raises(RemovalBlocked) as e:
+        _removal_gate(_dto(["Start"], ["a"]), _live(["Start"], ["a", "b"]))
+    assert e.value.removed["variables"] == ["b"]
+
+
+def test_the_message_names_what_would_disappear():
+    """The gate does not decide whether the removal is right - the caller does, from this
+    list. One line means an intentional edit; nine mean a lost picture of the flow."""
+    with pytest.raises(RemovalBlocked) as e:
+        _removal_gate(_dto(["Start", "Stop"], ["payload"]),
+                      _live(["Start", "Trim", "Normalize Diacritics", "Stop"],
+                            ["payload", "customerObj", "emailObj"]))
+    msg = str(e.value)
+    assert "2 action(s): Trim, Normalize Diacritics" in msg
+    assert "2 variable(s): customerObj, emailObj" in msg
+    assert "--allow-remove" in msg
+
+
+def test_allow_remove_lets_it_through():
+    ctx = _live(["Start", "Trim", "Stop"], ["a", "b"])
+    ctx["_allow_remove"] = True
+    _removal_gate(_dto(["Start"]), ctx)
+
+
+def test_generated_error_ports_are_not_authored_state():
+    """Error variables come and go with their owning action, so their absence from a
+    config is never the caller's removal."""
+    ctx = {"_live_flow": {"actions": [{"name": "Start"}], "variables": [
+        {"name": "a"}, {"name": "Trim_error", "isError": True}]}}
+    _removal_gate(_dto(["Start"], ["a"]), ctx)
+
+
+def test_pascal_and_camel_live_shapes_both_read():
+    """The live flow comes back camelCase from the API and PascalCase from a DTO round
+    trip; the gate must not go blind on either."""
+    ctx = {"_live_flow": {"Actions": [{"Name": "Start"}, {"Name": "Trim"}],
+                          "Variables": [{"Name": "a"}]}}
+    with pytest.raises(RemovalBlocked):
+        _removal_gate(_dto(["Start"], ["a"]), ctx)
+
+
+def test_no_live_flow_is_not_a_removal():
+    """A create, or an edit whose live read failed, has nothing to compare against - the
+    gate must stay out of the way rather than block on missing evidence."""
+    _removal_gate(_dto(["Start", "Stop"]), {})

procesio_cli/tools/procesio/tests/test_resource_ops.py

@@ -0,0 +1,173 @@
+"""CRUD-parity + oracle actions: correct endpoint/method, bodies, multipart import."""
+from __future__ import annotations
+
+import json
+
+from tools.procesio import main
+from tools.procesio.client import ProcesioClient
+from tools.procesio.tests.conftest import FakeResp, FakeSession
+
+APIKEY = {"type": "apikey", "key": "N", "value": "V"}
+
+
+def _builder(session):
+    return lambda prof: ProcesioClient(profile=APIKEY, name="t", session=session)
+
+
+def _call(action, argv, session):
+    return main.dispatch(action, argv, client_builder=_builder(session))
+
+
+def test_get_delete_list_endpoints():
+    # get
+    s = FakeSession(queue=[FakeResp(200, {"id": "F1"})])
+    out = _call("form-get", ["--id", "F1"], s)
+    assert s.calls[0]["method"] == "GET" and s.calls[0]["url"].endswith("/api/FormTemplate/F1")
+    assert out == {"result": {"id": "F1"}}
+    # delete
+    s = FakeSession(queue=[FakeResp(200, {})])
+    out = _call("process-delete", ["--id", "P1"], s)
+    assert s.calls[0]["method"] == "DELETE" and s.calls[0]["url"].endswith("/api/Projects/P1")
+    assert out == {"deleted": True, "id": "P1"}
+    # list (pageItems normalized)
+    s = FakeSession(queue=[FakeResp(200, {"pageItems": [{"id": "a"}, {"id": "b"}]})])
+    out = _call("document-list", [], s)
+    assert s.calls[0]["url"].endswith("/api/DocumentTemplate")
+    assert out == {"count": 2, "items": [{"id": "a"}, {"id": "b"}]}
+
+
+def test_toggle_activation_sends_the_state_header():
+    """The target state travels in a `state` header, not the body or the path.
+
+    Without it the endpoint deactivates every time while answering success, which is
+    what made it look, for a while, like an endpoint that could only turn things off.
+    """
+    s = FakeSession(queue=[
+        FakeResp(200, {"pageItems": [{"id": "P1", "active": False}]}),  # before
+        FakeResp(200, {"value": None, "errors": []}),                   # the PATCH
+        FakeResp(200, {"pageItems": [{"id": "P1", "active": True}]}),   # after
+    ])
+    out = _call("process-toggle-activation", ["--id", "P1", "--state", "true"], s)
+    patch = s.calls[1]
+    assert patch["method"] == "PATCH"
+    assert patch["url"].endswith("/api/Projects/P1/toggle-activation")
+    hdrs = {k.lower(): v for k, v in (patch.get("headers") or {}).items()}
+    assert hdrs.get("state") == "true", "the target state must be sent as the `state` header"
+    assert out["requested"] is True and out["active"] is True and out["changed"] is True
+    assert "warning" not in out
+
+
+def test_toggle_activation_deactivates_with_state_false():
+    s = FakeSession(queue=[
+        FakeResp(200, {"pageItems": [{"id": "P1", "active": True}]}),
+        FakeResp(200, {"value": None, "errors": []}),
+        FakeResp(200, {"pageItems": [{"id": "P1", "active": False}]}),
+    ])
+    out = _call("process-toggle-activation", ["--id", "P1", "--state", "false"], s)
+    hdrs = {k.lower(): v for k, v in (s.calls[1].get("headers") or {}).items()}
+    assert hdrs.get("state") == "false"
+    assert out["requested"] is False and out["active"] is False and out["changed"] is True
+
+
+def test_toggle_activation_warns_when_the_result_is_not_what_was_asked():
+    """The response is identical in every case, so only the read-back can disagree."""
+    s = FakeSession(queue=[
+        FakeResp(200, {"pageItems": [{"id": "P1", "active": False}]}),
+        FakeResp(200, {"value": None, "errors": []}),
+        FakeResp(200, {"pageItems": [{"id": "P1", "active": False}]}),  # asked true, still false
+    ])
+    out = _call("process-toggle-activation", ["--id", "P1", "--state", "true"], s)
+    assert out["requested"] is True and out["active"] is False
+    assert out["changed"] is False
+    assert "asked for active=True" in out["warning"]
+
+
+def test_toggle_activation_warns_when_it_cannot_confirm():
+    s = FakeSession(queue=[
+        FakeResp(200, {"pageItems": [{"id": "OTHER", "active": True}]}),  # P1 not present
+        FakeResp(200, {"value": None, "errors": []}),
+        FakeResp(200, {"pageItems": [{"id": "OTHER", "active": True}]}),
+    ])
+    out = _call("process-toggle-activation", ["--id", "P1", "--state", "true"], s)
+    assert out["active"] is None and "warning" in out
+    assert out["changed"] is None, "unknown must not read as 'did not change'"
+
+
+def test_form_duplicate():
+    s = FakeSession(queue=[FakeResp(200, {"id": "new"})])
+    out = _call("form-duplicate", ["--id", "F1"], s)
+    assert s.calls[0]["method"] == "POST" and s.calls[0]["url"].endswith("/api/FormTemplate/F1/duplicate")
+    assert out["duplicated"] is True
+
+
+def test_process_validate_empty_response_is_valid():
+    # GET the flow, then POST validate -> empty 200 body == valid
+    s = FakeSession(queue=[
+        FakeResp(200, {"flow": {"id": "P1", "title": "T"}}),
+        FakeResp(200, text="")])
+    out = _call("process-validate", ["--id", "P1"], s)
+    assert s.calls[0]["method"] == "GET" and s.calls[0]["url"].endswith("/api/Projects/P1")
+    assert s.calls[1]["method"] == "POST" and s.calls[1]["url"].endswith("/api/Projects/validate")
+    assert s.calls[1]["json"]["title"] == "T"             # posts the flow DTO
+    assert out["isValid"] is True and out["errors"] == []
+
+
+def test_process_validate_errors_surface():
+    # validator rejects -> platform 4xx with the error list -> isValid False + errors
+    s = FakeSession(queue=[
+        FakeResp(200, {"flow": {"id": "P1"}}),
+        FakeResp(400, {"body": [{"value": "Action has too many input ports."}]})])
+    out = _call("process-validate", ["--id", "P1"], s)
+    assert out["isValid"] is False
+    assert out["errors"] == [{"value": "Action has too many input ports."}]
+
+
+def test_webhook_launch_with_payload():
+    s = FakeSession(queue=[FakeResp(200, {"ok": True})])
+    out = _call("webhook-launch", ["--id", "W1", "--payload", '{"x":1}'], s)
+    assert s.calls[0]["method"] == "POST" and s.calls[0]["url"].endswith("/api/Webhooks/launch/W1")
+    assert s.calls[0]["json"] == {"x": 1} and out["launched"] is True
+
+
+def test_import_multipart(tmp_path):
+    bundle = tmp_path / "b.procesio"
+    bundle.write_bytes(b'{"Flows":[]}')
+    s = FakeSession(queue=[FakeResp(200, {"imported": 1})])
+    out = _call("import", ["--file", str(bundle)], s)
+    assert s.calls[0]["method"] == "POST" and s.calls[0]["url"].endswith("/api/Transport/import")
+    # ⚠ THE PART IS `importedData`, NOT `file`. This assertion previously
+    # encoded the wrong name: `POST api/Transport/import` documents the part as
+    # `importedData`, and the endpoint reports a wrongly named part only as a
+    # generic 403/MIGRATE, so nothing about the response would have revealed it.
+    field = s.calls[0]["files"]["importedData"]
+    assert field[0] == "b.procesio" and field[1] == b'{"Flows":[]}'
+    # ⚠ and all seven required boolean headers must go with it
+    sent = s.calls[0].get("headers") or {}
+    for wire in ("overrideData", "importDataTypes", "importFlows",
+                 "importCredentials", "importDocuments", "importForms",
+                 "importDataStores"):
+        assert sent.get(wire) == "true", "missing required header " + wire
+    assert out["imported"] is True and out["bytes"] == 12
+    # the captured headers also carry auth and user-agent, so the echo is
+    # compared as a SUBSET rather than for equality
+    assert out["headers_sent"].items() <= sent.items(), (
+        "the result must echo the flags it sent: a 403 from this endpoint "
+        "cannot be read without knowing what was asked")
+
+
+def test_credential_test_builds_dto_and_probes():
+    # GET /api/Credentials/types (template resolve), POST /api/Credentials/test (probe x2:
+    # once inside prepare_ctx, once in the action) -> return the last verdict
+    tmpl = {"name": "REST API", "gid": "G", "pid": "P",
+            "properties": [{"id": "u", "label": "URL", "validations": {"isRequired": True}}]}
+    def responder(method, url, kw):
+        if url.endswith("/api/Credentials/types"):
+            return FakeResp(200, [tmpl])
+        if url.endswith("/api/Credentials/test"):
+            return FakeResp(200, {"isSuccess": True})
+        return FakeResp(200, {})
+    s = FakeSession(responder=responder)
+    out = _call("credential-test", ["--config", json.dumps({"template": "REST API", "name": "x",
+                                                             "properties": {"URL": "https://a"}})], s)
+    assert any(c["url"].endswith("/api/Credentials/test") for c in s.calls)
+    assert out == {"tested": True, "isSuccess": True, "result": {"isSuccess": True}}

procesio_cli/tools/procesio/tests/test_save_validity.py

@@ -0,0 +1,207 @@
+"""The validity mark a save leaves behind, and the value a save reports.
+
+These pin behaviour measured against the live platform, not a reading of the docs:
+
+  * PROCESIO never computes `isValid`. It stores whatever the PUT body carries, and
+    defaults it to TRUE when the body omits the field.
+  * So a writer that passes a fetched flow straight through leaves a corrected process
+    marked broken for ever, and a writer that reports its own pre-save validation
+    describes the flow it sent rather than the one the platform kept.
+
+Both were real: `node-set-param` on a correct process marked invalid reported
+`isValid: true, put: true` while the server went on holding `isValid: false`.
+
+A fake client throughout - no network.
+"""
+import pytest
+
+from tools.procesio.handlers import fevalidate
+
+
+class _Server:
+    """A PROCESIO that stores `isValid` verbatim and never recomputes it - which is
+    exactly what the live one was measured doing."""
+
+    def __init__(self, stored_valid=False, fe_clean=True, be_valid=True):
+        self.stored = {"id": "p1", "isValid": stored_valid, "variables": [], "actions": []}
+        self.fe_clean = fe_clean
+        self.be_valid = be_valid
+        self.puts = []
+
+    def get(self, path, query=None):
+        if path.startswith("/api/DataTypes"):
+            return {"pageItems": []}
+        if path.startswith("/api/Projects/"):
+            return {"flow": dict(self.stored)}
+        return {}
+
+    def post(self, path, body=None, query=None):
+        if path == "/api/Projects/validate":
+            return {"raw_text": ""} if self.be_valid else {"errors": ["bad runtime"]}
+        return {}
+
+    def put(self, path, body=None, query=None):
+        self.puts.append(body)
+        self.stored["isValid"] = body.get("isValid")   # verbatim, like the real one
+        return {"raw_text": ""}
+
+
+def test_a_clean_save_clears_a_stale_invalid_mark():
+    """The reported symptom: fix the process, save it, and it stays marked broken."""
+    srv = _Server(stored_valid=False)
+    flow = {"id": "p1", "isValid": False}
+    out = fevalidate.save_flow(srv, flow, flow_id="p1", valid=True)
+    assert srv.stored["isValid"] is True, "the save must clear the stale mark"
+    assert out["isValid"] is True, "and must report what the server now holds"
+
+
+def test_the_reported_value_is_re_read_not_the_value_we_sent():
+    """A server that disagrees with the body must be believed over our own measurement."""
+    srv = _Server(stored_valid=False)
+
+    def stubborn_put(path, body=None, query=None):
+        srv.puts.append(body)          # accepts the write, keeps its own answer
+        return {"raw_text": ""}
+    srv.put = stubborn_put
+
+    out = fevalidate.save_flow(srv, {"id": "p1"}, flow_id="p1", valid=True)
+    assert out["stamped"] is True, "we asked for valid"
+    assert out["isValid"] is False, "but the server kept false, and that is what is reported"
+
+
+def test_an_invalid_flow_is_stamped_invalid_rather_than_left_alone():
+    """Saving a half-built process is intended; marking it valid is not."""
+    srv = _Server(stored_valid=True)
+    out = fevalidate.save_flow(srv, {"id": "p1", "isValid": True}, flow_id="p1", valid=False)
+    assert srv.stored["isValid"] is False
+    assert out["isValid"] is False
+
+
+def test_the_field_is_never_omitted():
+    """Omitting it makes the platform default to true, which marks broken work valid."""
+    srv = _Server()
+    fevalidate.save_flow(srv, {"id": "p1"}, flow_id="p1", valid=False)
+    assert "isValid" in srv.puts[0], "the body must carry the mark explicitly"
+    assert srv.puts[0]["isValid"] is False
+
+
+def test_a_failed_read_back_does_not_fail_a_save_that_landed():
+    srv = _Server()
+
+    def blind_get(path, query=None):
+        if path.startswith("/api/Projects/"):
+            raise RuntimeError("read-back unavailable")
+        return {"pageItems": []}
+    srv.get = blind_get
+
+    out = fevalidate.save_flow(srv, {"id": "p1"}, flow_id="p1", valid=True)
+    assert srv.puts, "the PUT still happened"
+    assert out["isValid"] is None
+    assert "readback_error" in out
+
+
+def test_every_surgical_writer_goes_through_the_stamping_save():
+    """No handler may PUT a fetched flow directly: that is how the mark went stale."""
+    import pathlib
+    root = pathlib.Path(fevalidate.__file__).resolve().parent
+    for name in ("nodeparams.py", "sqlactions.py"):
+        src = (root / name).read_text(encoding="utf-8")
+        assert 'client.put("/api/Projects", flow)' not in src, (
+            f"{name} PUTs a fetched flow directly; use fevalidate.save_flow so the "
+            "validity mark is stamped and the stored value re-read")
+
+
+def test_a_forced_save_does_not_file_a_broken_process_as_valid():
+    """build() hardcodes IsValid=True; the gate must overwrite it with the verdict.
+
+    Without this, `process-edit --force` - the supported way to save half-finished work -
+    marked every broken process valid, and the designer's own error list disagreed with
+    the flag stored beside it.
+    """
+    from tools.procesio.dto.process import builder as pb
+
+    class _C:
+        def get(self, path, query=None):
+            return {"pageItems": []} if path.startswith("/api/DataTypes") else {"flow": {"variables": []}}
+
+        def post(self, path, body=None, query=None):
+            return {"raw_text": ""}          # BE says valid; the designer will not
+
+    dto = {"IsValid": True, "Actions": [], "Variables": []}
+    pb._save_gate(_C(), dto, {"_force": True})
+    assert dto["IsValid"] is False, "a flow with no Start/Stop is not valid, forced or not"
+
+
+def test_a_clean_save_still_stamps_valid():
+    from tools.procesio.dto.process import builder as pb
+
+    class _C:
+        def get(self, path, query=None):
+            return {"pageItems": []} if path.startswith("/api/DataTypes") else {"flow": {"variables": []}}
+
+        def post(self, path, body=None, query=None):
+            return {"raw_text": ""}
+
+    def act(aid, name, tmpl, ports):
+        return {"id": aid, "actionName": name, "actionTemplateName": tmpl,
+                "customData": {"type": "square", "name": name, "configuration": []},
+                "ports": ports}
+
+    dto = {"IsValid": True, "Variables": [], "actions": [
+        act("start", "Start", "Start", [{"sourceId": "start", "destinationId": "stop"}]),
+        act("stop", "Stop", "Stop", [])]}
+    pb._save_gate(_C(), dto, {})
+    assert dto["IsValid"] is True
+
+
+def test_no_process_writer_anywhere_puts_a_flow_without_stamping_it():
+    """The rule is repo-wide, not per-handler: every save decides the mark.
+
+    A rename or a re-layout is a save like any other, and leaving those two as
+    pass-throughs meant the fixed bug could walk back in through the least
+    suspicious door - renaming a node should not be able to file a repaired
+    process as broken.
+
+    process_layout and process_naming are included deliberately. dto/process/builder
+    is not: it stamps in its own save gate, which covers create and edit together.
+    """
+    import pathlib
+    root = pathlib.Path(fevalidate.__file__).resolve().parent
+    for name in ("nodeparams.py", "sqlactions.py", "process_layout.py", "process_naming.py"):
+        src = (root / name).read_text(encoding="utf-8")
+        for bad in ('client.put("/api/Projects", flow)',
+                    'client.put("/api/Projects", new_flow)'):
+            assert bad not in src, (
+                f"{name} PUTs a fetched flow directly; route it through "
+                "fevalidate.save_flow so the mark is stamped and re-read")
+
+
+def test_save_arranges_the_canvas_by_default(monkeypatch):
+    from tools.procesio.handlers import fevalidate
+    monkeypatch.delenv("PROCESIO_KEEP_LAYOUT", raising=False)
+    called = {}
+    monkeypatch.setattr(fevalidate, "arrange", lambda f: (called.setdefault("flow", f), "arranged"))
+
+    class Srv:
+        def put(self, path, body):
+            self.body = body
+
+        def get(self, path, query=None):
+            return {"flow": {"isValid": True}}
+    out = fevalidate.save_flow(Srv(), {"id": "p1"}, flow_id="p1", valid=True)
+    assert called and out["layout"] == "arranged"
+
+
+def test_save_keeps_the_canvas_when_asked(monkeypatch):
+    from tools.procesio.handlers import fevalidate
+    monkeypatch.setenv("PROCESIO_KEEP_LAYOUT", "1")
+    monkeypatch.setattr(fevalidate, "arrange", lambda f: (_ for _ in ()).throw(AssertionError("must not arrange")))
+
+    class Srv:
+        def put(self, path, body):
+            pass
+
+        def get(self, path, query=None):
+            return {"flow": {"isValid": True}}
+    out = fevalidate.save_flow(Srv(), {"id": "p1"}, flow_id="p1", valid=True)
+    assert out["layout"] == "kept"