procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/PROCESIO-FOREACH-NOTES.md

@@ -0,0 +1,199 @@
+# PROCESIO `For Each` — construction quirks and the loop-timeout trap
+
+The `For Each` action is template id **`dbef0804-66a9-4f8f-872c-ece1b89b8fdb`**.
+Body membership is by **`ParentId`** (a child action's `parentId` == the loop's
+id), never by an enclosing edge, and only `TemplateId` identifies the action —
+`ActionTemplateName` is `null` on ~half of the corpus's For Each nodes and
+`ActionName` is free text.
+
+## ⚠⚠ A programmatically-built For Each is missing two parameters a designer-built one has
+
+> ✅ **FIXED IN THE BUILDER (E-160, 28/08/2026).** `dto/process/builder.py` now
+> materialises the two template-default output params at build time, so a `For Each`
+> built through `process-create` / the compact config **iterates out of the box** — no
+> post-create splice. See `_template_default_params` and the "the fix" section below.
+> The description that follows is the diagnosis that led there; the workaround at the
+> bottom is retained only as history and is **no longer needed**.
+
+Read from live flows, the same `For Each` template carries a **different
+parameter set** depending on how it was created:
+
+| built how | `tabPropertyId` suffixes present | Action timeout |
+|---|---|---|
+| **designer (GUI)** | `…55f8c7` (For Each Item), `…adae8b` (In List), `…df9db1` (Action timeout), **`…61724e` = `"-1"`**, **`…808b0d` = `"2010-01-01T00:00:00.0000000Z"`** | commonly 600 |
+| **programmatic** (compact config → `process-create`, or hand-built flow JSON) | `…55f8c7`, `…adae8b`, `…df9db1` only | whatever you set |
+
+The programmatic build path **omits `…61724e` and `…808b0d`**, and they are **not
+defaulted in on save/validate** — the flow validates and creates cleanly with
+three parameters.
+
+## ⚠⚠ The failure mode: the loop times out without iterating a populated list
+
+A For Each carrying only the three parameters has been observed to **fail to
+iterate a list that is demonstrably populated and correctly bound**, returning:
+
+```
+status 40
+{"errorMessage": "Foreach timeout exceeded!", "actionName": "...", "actionType": "For Each"}
+```
+
+after the loop's `Action timeout` seconds, **writing nothing** — no body child
+executes even once. This was isolated hard:
+
+- The `In List` parameter **is** bound (its `variable[0].variableId` points at the
+  list variable) — verified by reading the created flow back; it is not a
+  null/unbound-list problem.
+- The list variable **is** populated at runtime — the same run that times out
+  returns the list (e.g. 3 elements) in its output variables.
+- A **no-loop** flow proves the pieces are healthy: the list-producer Node yields
+  the elements, a Node reads them, and a Data Store `InsertRows` writes a row —
+  all at **status 50**. Only inside the For Each does it hang.
+- Reproduced in a **minimal** For Each (one Node → the loop → one Data Store
+  `InsertRows` body child), independent of the body's contents and of whether the
+  body's `InsertRows` binds the loop item directly or a pick-Node-derived scalar.
+
+## ⚠⚠ CONFIRMED (causal test done): the two parameters ARE the cause, and the timeout is NOT
+
+The leaf-diff causal test is now performed. Splice **EXACTLY** `…61724e` = `"-1"`
+and `…808b0d` = `"2010-01-01T00:00:00Z"` onto a live 3-parameter loop via
+`put-projects`, **change nothing else**, re-run, and judge on rows landed:
+
+| the same loop, only these two parameters differ | body executions | status |
+|---|---|---|
+| 3-parameter (as `process-create` builds it), populated list | **0** | 40 `Foreach timeout exceeded!` |
+| **+ `…61724e` + `…808b0d`** (Action timeout left **unchanged**) | **3** (full) | 50 |
+
+Measured twice, independently: **0 → 3 on a minimal loop**, and **entry 3 / body 3 /
+real inserts 3 of 3** on a two-loop diff flow.
+
+- ⚠⚠ **The Action timeout does NOT matter.** The designer loop's `…df9db1` is 600
+  and the programmatic one's is 120; the splice **held it at 120** and the body ran.
+  The two output parameters alone are sufficient — do **not** raise the timeout as
+  part of the "fix" (that would be two changes at once and mis-attribute the cause).
+- ⚠⚠ **Both are OUTPUT parameters** (`direction 2`, type `ignore`): `…61724e`
+  "Zero based list index" (the current-iteration counter) and `…808b0d` "Action
+  start time". A loop with no index slot has nowhere to advance the iteration index,
+  consistent with never entering the body — mechanism plausible, the *measurement*
+  is that adding exactly these two flips 0 → N.
+- ⚠⚠ **The omission is in OUR builder, not the platform (E-158 refinement — A-42
+  WITHDRAWN as a platform defect).** The two output parameters are the `For Each`
+  template's **own default-valued settings**: the live action catalog shows template
+  `dbef0804` declaring `61724e` "Zero based list index" with default `value` `"-1"`
+  and `808b0d` "Action start time" with default the `2010-…Z` sentinel — both
+  `direction 2`, `type ignore`, **`isRequired false`**. The DESIGNER materialises every
+  template setting into the flow; the compact-config builder
+  (`dto/process/builder.py::_action_parameters`) is **binding-driven** — it emits one
+  parameter per config *binding* and never walks the template's settings — so a param no
+  one binds (a runtime-written output with a default) is never emitted. Neither API path
+  defaults it in on save. **So the fix belongs in the builder: materialise the template's
+  default-valued output settings** (at minimum emit these two for `For Each`; generally,
+  any `direction:2/type:ignore` setting carrying a template `value`). Because the
+  validator keys on `isRequired`, a 3-param loop validates + creates clean and only fails
+  at runtime with the generic timeout — a genuinely platform-side rough edge, but a minor
+  quality/parity note, not the "build path is broken" claim.
+- ✅ **DONE (E-160). The builder now materialises them.** `dto/process/builder.py`
+  gained `_is_template_default_output` (predicate: `direction:2` or `type:ignore` with a
+  non-empty scalar `value`) and `_template_default_params` (walks the template, emits
+  `{TabPropertyId, Value:<default>, Variable:[]}` for each such setting not already
+  produced by a binding, deduped by `TabPropertyId`), called in `build()` after the
+  binding-driven / doc-mapper / decisional / subprocess params. It is **template-driven,
+  not a For-Each special-case**: `For Each` gains `61724e`/`808b0d`, and `Call
+  Subprocess`'s `a03fe2` started-flow slot (the only other member of the class in the live
+  233-action catalog) is subsumed — already emitted by `_build_subprocess`, so the dedupe
+  makes it a no-op there. Proven a TRANSFORM (a process with no such setting builds
+  byte-identical; `For Each` differs by exactly the two params appended) and proven LIVE
+  (a loop built by `process-create` iterates 3, no splice; both loops of a two-loop flow
+  iterate → status 50, where the E-150 single-loop splice left status 40). ⚠ A separate,
+  larger class is NOT fixed: 40 actions carry INPUT-side (`direction:1`) template defaults
+  the builder also drops when unbound — untested whether it matters; see
+  `todo/procesio-builder-input-default-materialisation.md`.
+- ⚠ **`put-projects` cannot create — it is PUT/edit only.** A create DTO (fresh
+  client-supplied Id) PUT to `put-projects` returns HTTP 400 / statusCode 502 "missing or
+  incorrect resource parameters" and persists nothing; creation is **POST /api/Projects**
+  (what `process-create` wraps). As a save path `put-projects` stores the parameter set
+  literally — it does NOT materialise template defaults either. So there is no alternative
+  API build path that carries the two params for you; a loop built + saved via
+  `put-projects` iterates iff they are present (measured 0→3 on the same object).
+- ✅ **Workaround (HISTORY — no longer needed since E-160):** before the builder fix,
+  the way to iterate was, after `process-create`, to read the flow back, append the two
+  parameter objects to the loop action's `parameters`, and `put-projects` (verify by
+  reading the loop's `parameters` back — 5 present, originals unchanged — before running).
+  The builder now emits the two at create, so this post-create splice is retired. ⚠ One
+  fact from it that still applies to any read-back diff: **on save the platform
+  normalises `…808b0d` from `"…00.0000000Z"` to `"…00:00:00Z"`** — the same parameter;
+  tolerate the trailing-precision reformat when you diff a stored loop.
+
+The parameter objects to append (authoritative `parameters`-array form):
+`{"tabPropertyId":"99e8766d-d6be-4948-8f57-1f141f61724e","value":"-1","variable":[]}`
+and `{"tabPropertyId":"9d2d3483-f04b-48ac-9dea-2ef7ae808b0d","value":"2010-01-01T00:00:00.0000000Z","variable":[]}`.
+
+## Diagnosing a For Each that "does nothing"
+
+- **Prove the loop's INPUT is populated before you read its zero — a wrong-shaped
+  run payload reads identically to a dead loop.** If the flow's input variable is
+  supplied in the wrong shape (e.g. a bare list where the process declares
+  `{source, tenant}`), the input variable is left empty, any pre-loop JavaScript
+  node that substitutes it via `<%N%>` dies with **`"Unexpected token ';'"`** (an
+  empty token becomes `var x = ;`), the list the loop iterates comes back **null**,
+  and the loop iterates nothing — indistinguishable from the parameter-omission
+  hang unless you check the pre-loop nodes' error variables and the list length.
+  Gate on: the pre-loop nodes ran clean AND the In-List variable is the expected
+  length, THEN read the loop's body count.
+- **A body node that never ran reports no error.** Clean per-node error variables
+  are NOT evidence the body executed. Get positive evidence out-of-band: a Data
+  Store `InsertRows` in the body writing to a disposable store, read from OUTSIDE
+  the flow — a timeout can suppress every *returned* output variable (observed:
+  `vars: {}` on a timed-out run), so never rely on a value returned into a flow
+  variable to prove the body ran. Prove that marker can write with a **no-loop**
+  run first, or its zero is uninterpretable.
+- **Judge a loop on rows landed, not status.**
+- **`For Each` takes ONE input port.** Two loops in sequence, or a body-exit and
+  the loop-continuation both reaching the same downstream node, need a `Join`
+  between them, or the back end refuses `statusCode 383 "Action has too many
+  input ports."` on save.
+- A **list**-returning Node binds its result via the **`List Result`** parameter
+  (`…60237e88`); a scalar via **`Single Result`** (`…51b9fcdc`). Wrong one → the
+  list variable is never assigned and the loop iterates null (also a timeout).
+
+## Related Data Store facts used above
+
+- A Data Store **must have a primary key** — `datastore-from-json` without
+  `primaryKeyAttributeNames` is refused `502 "At least one column must be marked
+  as a primary key."` So you cannot append identical rows as a pure log; a
+  per-row distinct key is required to count iterations by row.
+- Inside a For Each, per-iteration **single** `InsertRows` calls write N distinct
+  rows correctly (this is the working idiom); the **collapse-to-one** failure is a
+  *batch* insert of a parallel-list mapper in a single call, a different path.
+
+## Landing N rows: the working shape, its body-port wiring, and the re-run NOOP
+
+Confirmed end to end (a multi-row landing card, 2026-09-02): to write **N rows to a
+store from one run**, loop a **model-typed list** and do **one `InsertRows` per
+iteration** binding the loop ITEM's data-model attributes. Concretely:
+
+- **The list and the item are both typed as the store's data model.** A Node emits the
+  list bound via **`List Result`** (not `Single Result`); the For Each's **`For Each
+  Item`** output is bound to a NON-list variable of the same model type; the body
+  `InsertRows` Set-Values mapper binds `item.<attr>` exactly as the single-row splice
+  does (b017 pattern), only the bound variable is the loop item, not a standalone one.
+- **Body-port wiring (edges, not just `parent`).** The `parent` key on the body action
+  sets ParentId (visual containment) but gives it **no ports** — ports come from edges.
+  Read from a designer export, a For Each with one body child carries **two out-ports on
+  the loop** (loop → continuation, e.g. the Join; and loop → body child) **plus one
+  out-port on the body child back to the loop** (body → loop). So the compact-config
+  edges are: `[loop, <next>]`, `[loop, <body>]`, `[<body>, loop]`. Omit the last two and
+  the build validates but the body node fails with **statusCode 390/391 "Action has too
+  few input/output ports."** The platform infers body-vs-continuation from the child's
+  ParentId, so edge order does not matter; supply all three edges.
+- **Idempotency comes free from the store PK — do NOT write dedupe logic.** Give each row
+  a **deterministic natural key** (stable per input, unique within the batch, e.g.
+  `<tool>:<table>:r<zero-padded-index>`). A fresh batch lands all N at **status 50**; a
+  re-run of the same input replays the same keys and the store PK rejects the duplicates,
+  so the instance **halts at status 40 with nothing written twice** — a clean NOOP, the
+  same dup-PK guard a single-row card shows (a re-run "must be a NOOP, not a double-load"
+  is satisfied by this alone). Validate the WHOLE input up front (count, shape, any
+  ceiling) and emit rows only on the clean branch, so a bad input never starts a partial
+  loop; then the only mid-loop halt is a dup key, which is the desired NOOP.
+- **Cost scales with N.** One native `InsertRows` per row is billed per row: measured
+  `timeConsumed ≈ fixed + ~14 ms × N` (vs a single-insert card that bills flat). Size the
+  loop to the real table; a very large table is a v2 concern (bulk import), not this shape.

procesio_cli/tools/procesio/PROCESIO-FORM-API-HANG-NOTE.md

@@ -0,0 +1,101 @@
+> ## ⚠ SUPERSEDED (re-probed 2026-09-03): `form-get` does NOT hang
+>
+> `GET /api/FormTemplate/{id}` returned a 342 KB DTO in seconds, repeatedly, and every
+> read-modify-write action built on it (`form-get-element-events`, `form-set-element-event`,
+> `form-add-element`, `form-set-element-config`) worked. Whatever caused the original hang is
+> not reproducible on this installation.
+>
+> **Why this matters more than a stale row:** the note below steers the reader away from the
+> surgical read-modify-write path and toward full rebuilds, which is the riskier route on a
+> live form. Treat the table as history. Re-probe before believing any "this call hangs"
+> claim — an intermittent or since-fixed hang reads identically to a permanent one.
+
+# PROCESIO forms over the API — what works, and the one call that hangs
+
+Live-probed while shipping a form for a marketplace template. The folklore is "form
+creation hangs over the API". That is **wrong, and the imprecision costs a build**: creation
+is fine. The call that hangs is the **read**.
+
+| Call | Endpoint | Result |
+|---|---|---|
+| `form-create` | `POST /api/FormTemplate` | ✅ **works** — returns the new form id; the form renders with all its controls |
+| `form-list` | `GET /api/FormTemplate/all/basic` | ✅ works (fast) |
+| `get-customurl-formtemplate-by-id` | `GET /api/CustomUrl/FormTemplate/{id}` | ✅ returns (empty until a CustomUrl is minted) |
+| **`form-get`** | **`GET /api/FormTemplate/{id}`** | ❌ **HANGS** — no response, no error; killed at 90s |
+
+## The consequence: nothing that must READ a form first can run
+
+Every surgical/read-modify-write form action reads the form before writing, so they all
+inherit the hang: `form-set-element-event` (wiring a control to `RUN_PROCESS`),
+`form-set-element-config`, `form-get-element`, `form-get-element-events`, `form-set-code`,
+`form-update`, `form-edit`. A wiring dry-run never even reaches its write.
+
+**Practical rule:** everything a form needs must be expressed in the **single `form-create`
+call**, because you may not get a second bite at it over the API. Build the complete element
+tree, theme, and (where the builder supports it) events in that one create. If a form must
+be adjusted afterwards, expect to do it in the designer UI.
+
+**Do not** try to work around the hang by re-creating the form on every change: each
+`form-create` mints a NEW form id (and any URL you minted points at the old one). Prefer one
+correct create, then the UI.
+
+## Wiring a form's submit to a process, in the UI (the fallback recipe)
+
+1. Open the form in the designer, select the submit button, add an event on **click**:
+   **Run process** → pick the process.
+2. Turn **syncRun ON** ("wait for the process to finish"). With it off, the form fires and
+   forgets and no output can ever populate.
+3. Map **inputs**: each form field → the matching process input variable (file upload →
+   the `FileDataModel` input; a file control already holds a *list*, which is what a
+   file-typed process input expects).
+4. Map **outputs** the same way if results are shown back on the form. Design rule: one
+   output variable per field, all primitives — mapping one structured object
+   attribute-by-attribute is what produces `[object Object]` in every field.
+5. Publish, then mint the public URL (CustomUrl) if the form should be reachable
+   without a login.
+
+## Wire the process INSIDE the create — it works, and it is the only way here
+
+Because `form-set-element-event` cannot run (it reads first), declare the trigger in the
+`form-create` config itself. The builder resolves names on both sides, so the config stays
+readable and no GUIDs are hand-written:
+
+```json
+{"type":"button","name":"btn_run","label":"Run","submit":true,
+ "events":[{"on":"click","do":"process","processId":"<pid>","syncRun":true,
+   "inputs":  [{"to":"<process input var>", "from":"<form field name>"}],
+   "outputs": [{"to":"<form field name>",   "from":"<process output var>"}]}]}
+```
+
+Verify the built DTO before trusting it: every map row's form side must be a 4-segment
+value path (`formId.FIELDS_NS.elementId.valueConfigId`). A row still holding the raw field
+**name** is silently broken - the API accepts it, the designer renders it blank, and the
+field never populates.
+
+### Two builder defects this exposed (both fixed in `dto/form/builder.py`)
+
+1. **Field paths resolved in declaration order.** `ctx['field_paths']` is filled as
+   elements are built, so a trigger declared *above* its target fields could not resolve
+   them. That is the normal layout for any form that shows results (the submit button sits
+   above the results panel), so every output map silently kept raw names. Fixed with a
+   second pass (`_resolve_late_field_refs`) that re-resolves event map rows once every path
+   is known; declaration order no longer changes the wiring.
+2. **Controls whose value config is not called `value` never registered a path.** A
+   `file-viewer` holds its file in **`src`** (its own empty state reads "Field source not
+   set"), while `_VALUE_TYPE` already types it as File. So it received a data-model
+   attribute but no field path, and could not be targeted by an output map. Fixed with
+   `_VALUE_CONFIG_KEY` / `_value_key()`, used for both path registration and the
+   data-model attribute typing, so `src` is typed File rather than String.
+
+**Design rule that still applies:** one output variable per field, all primitives. Add a
+small splitter action per display field that returns a plain string, rather than mapping
+one structured object attribute by attribute (which writes `[object Object]` everywhere).
+
+## Building the form in one create — shape that worked
+
+`form-create --config-file` with a flat `elements` list; each control is
+`{type,label,name,required,...}` and the submit is `{"type":"button","submit":true}`.
+Types used successfully: `heading`, `paragraph`, `file-upload`, `datetime-input`, `input`,
+`number-input`, `button`. `isPrivate:false` + `publish:true` makes it public and published.
+A control's `name` is also the **URL query-param key** for pre-filling, so pick stable,
+URL-safe names.

procesio_cli/tools/procesio/PROCESIO-FORM-SUBMISSION-NOTES.md

@@ -0,0 +1,172 @@
+# Submitting a PROCESIO form programmatically, and why you must
+
+How to run a process **through its form** rather than through the process API, using the
+public `FormProcess` endpoints, and the class of defect that only this catches.
+
+## Why the process API is not enough
+
+A form and the process behind it are assembled separately, and **nothing in the platform
+asserts that the two agree**. Two failure modes follow, both of which pass every
+process-side assertion ever written:
+
+1. **A submit button wired to nothing.** The form validates, publishes, renders, collects
+   every field, and discards all of it. Process-side tests never touch the form, so they
+   stay green.
+2. **An input that is collected, mapped, and never consumed.** The variable exists, the
+   form sends it, the engine receives it, and no action reads it. The feature it appears to
+   offer silently does nothing, and the value shown to the user is whatever the code
+   hardcoded.
+
+Both are invisible to an API-only test suite and to a green run. Treat a form-surface
+submission as part of acceptance, not as an extra.
+
+## The call sequence (mirrors the process side, different routes and headers)
+
+Every `FormProcess` route is **anonymous** and scoped entirely by the
+`formTemplateWorkspaceId` **header**. Omit it and the API answers
+`Invalid request due to missing or incorrect resource parameters. target: form template`.
+
+| Step | Call | Notes |
+|---|---|---|
+| 1 publish | `POST /api/FormProcess/{formTemplateId}/{processTemplateId}/publish` | body = the input payload keyed by **process variable name**; files are staged as **metadata only** `{path:"",size,mimeType,name,id:<client uuid>,hash:""}` |
+| 2 upload | `POST /api/FormProcess/{formTemplateId}/{flowInstanceId}/upload` | `multipart/form-data`, field name **`package`**, headers `flowTemplateId`, `variableName`, `fileId`, `formTemplateWorkspaceId` |
+| 3 launch | `POST /api/FormProcess/{formTemplateId}/{instanceId}/launch?runSynchronous=true&secondsTimeOut=N` | body `{connectionId, flowTemplateId}` |
+| 4 read | `GET /api/FormProcess/{formTemplateId}/{processTemplateId}/{processInstanceId}/variables` | |
+
+**The launch route's second path segment is the INSTANCE, not the process template**, even
+though the API reference names it `processTemplateId`. The give-away is that the body
+already carries `flowTemplateId`, which would be redundant otherwise; the process-side
+equivalent (`/api/Projects/instances/{instanceId}/launch`) has the same shape. Verified
+live: launching with the instance in that slot succeeds.
+
+**The variables response carries runtime values in `defaultValue`, not `value`.** The
+endpoint returns variable *definitions*. Reading `value` yields `None` for every output and
+looks exactly like "the form produced nothing", which is the same false negative this
+whole exercise exists to prevent. Flatten to `{name: defaultValue}` before asserting.
+
+Implemented as the curated action `run-form-with-files` (the generated `<method>-<path>`
+actions cannot reach it: they send JSON only, with no custom headers and no multipart).
+
+## The contract check, as a standard
+
+Run this for every card that ships a form. It is three layers, and the third is the one
+that cannot be faked:
+
+1. **Every form input reaches the engine.** Each `inputMap` row's process side resolves to a
+   real input variable, and its form side resolves to a **4-segment value path**. A row left
+   holding a raw field *name* is accepted by the API, renders blank in the designer, and
+   never carries a value.
+2. **Every engine output reaches a pane.** Any output with no `outputMap` row is either a
+   missing pane or a machine-only channel. See the exemption rule below.
+3. **Every input is consumed by the logic.** Cross-reference each input variable against every
+   action's parameter bindings. An input bound by nothing is a **defect, not a spare**. Then
+   prove it end to end: submit through the form surface and assert that a value entered on the
+   form is visible in the rendered output. A tolerance, a threshold or a label is ideal,
+   because a wrong one is invisible in a green run.
+
+Layers 1 and 2 read the live DTOs and cost nothing. Layer 3 needs one real submission.
+
+## The named machine channel: how to have an exception without losing the rule
+
+A strict rule with no exit becomes a rule people switch off. A rule with a silent exit stops
+being a rule. The way to keep both is a **declared exemption**: a machine-only output is
+listed by name in the checker, so it passes and the pass is visible.
+
+```python
+# Outputs that exist for assertions and API callers, not for a pane.
+# Named explicitly so the exemption shows up rather than being assumed.
+MACHINE_ONLY = {"recon"}
+```
+
+The check then reports `output 'recon' is a declared machine channel, no pane expected`
+instead of either failing a legitimate design or silently skipping it. Three properties make
+this honest, and they generalise to any strict gate:
+
+- **It is enumerated, not inferred.** No pattern match on names, no "outputs starting with an
+  underscore are internal". Someone had to type the name.
+- **It appears in the output.** The exemption is a line in the report, so a reviewer sees the
+  exception was taken and can challenge it.
+- **It is per-artefact and small.** A growing allowlist is itself the signal that the design
+  drifted, which a blanket `--skip-outputs` flag would hide.
+
+Never widen this to a category ("all Json outputs are machine channels"). The moment the
+exemption is a class rather than a list, a genuinely missing pane joins it unnoticed, and the
+gate goes back to passing the defect it was built to catch.
+
+## A RUN_PROCESS event that never reads its result
+
+Two separate settings decide whether a form learns anything from the process it launched, and a
+form can be missing both while looking completely wired in the designer:
+
+- **`syncRun: false`** — the event fires and the form moves on. Nothing downstream can see a result.
+- **`outputMap: []`** — even a synchronous run maps nothing back, so the process's output variables
+  stay inside the process.
+
+With both, the form falls through to its generic `SUBMIT_SUCCESS` message whatever happened, so a
+refusal ("that slot is taken", "invalid email", a rate-limit) is indistinguishable from a booking
+that was written. This is the form-side twin of the `Execute Command` result-set defect
+(PROCESIO-SQL-ACTIONS-NOTES.md): at every layer the failure mode is *the outcome is discarded and
+success is assumed*, and at every layer it is invisible to validation and to a green run.
+
+**The shape that works** — three events on one button, in this order:
+1. `RUN_JAVASCRIPT` — validate, then write the process inputs into `ProcesioForm.variables`.
+2. `RUN_PROCESS` — `syncRun: true`, `inputMap` from those variables, `outputMap` from the
+   process's output variable into a FORM variable.
+3. `RUN_JAVASCRIPT` — read that form variable and render the real outcome.
+
+`form-set-element-event --replace-action RUN_PROCESS` swaps step 2 in place, preserving the other
+events and their order; a plain call appends, which is how step 3 lands last.
+
+**A result-set output arrives as a LIST even when it is one row**, so step 3 must take `[0]` (and
+tolerate a non-array). Guard the success test on both `true` and `1` — the same field comes back
+as a SQL bit and as a JSON boolean depending on the path.
+
+**Do not hand-escape values in the form's JavaScript.** A `.replace(/'/g, "''")` in a submit
+handler is a sign the process is string-interpolating SQL rather than binding parameters. Fix the
+process (`sql-parameterize`), then delete the escaping: it is not a control (the process endpoint
+is callable directly, without the form) and it corrupts legitimate input.
+
+### Map rows: `isList` is not cosmetic
+Each side of an `inputMap` / `outputMap` row is an object, `{value, isList, path}`. Binding a
+list-valued variable with `isList: false` puts the whole result set into a scalar slot: the form
+receives nothing, and both the API and the designer accept the row without complaint. `path` is
+`{}` on the process side; on the form side it is `{}` for a form VARIABLE and `null` for a form
+FIELD target.
+
+## A `paragraph` renders its `label`. Writing `.value` paints nothing.
+
+The single highest-yield form gotcha found so far, because it fails in the direction that looks
+fine: `ProcesioForm.data.fields.SomeParagraph.value = '…'` is accepted, throws nothing, logs
+nothing — and the page keeps its original placeholder text. A handler written that way reports
+nothing at all to the visitor, whatever happened underneath.
+
+```js
+function say(text) {                      // set BOTH: a field control does read .value
+  const m = ProcesioForm.data.fields.BookingMessage;
+  m.label = text; m.value = text; m.visible = true;
+}
+```
+
+Verified live both ways on a published form: with only `.value` the DOM text was unchanged after a
+successful run; with `.label` the new text appeared. Assume the same for any control whose text is
+authored as a label (heading, paragraph) rather than typed into by the user.
+
+**Test it by reading the DOM, not the handler.** The handler running is not evidence the reader saw
+anything — `document.body.innerText` before and after the click is.
+
+## Driving a published form headlessly, without a compositing browser pane
+
+Two facts make a real end-to-end click-through possible even when no pane is displayed and trusted
+mouse events are unavailable:
+
+1. **`element.click()` works on a PROCESIO form button.** The whole event chain fires — the JS
+   handlers, the RUN_PROCESS, the result handler. Confirmed by the process instance appearing in
+   `list-instances` attributed to the form, and by the row changing in the database.
+2. **Every control pre-fills from a URL query parameter named after the control** — including
+   `visible: false` controls, whose values reach the process even though they are not in the DOM at
+   all. That is what makes a hidden-token page (a cancel link) work, and it also lets a test skip
+   custom pickers (dropdown, date, slot list) that need trusted events: pass their values on the
+   query string instead.
+
+So: navigate with the fields on the query string, `.click()` the button, then read
+`document.body.innerText`. That is a genuine test of the deployed form, not a stub.

procesio_cli/tools/procesio/PROCESIO-HTML-TO-DOCX-NOTES.md

@@ -0,0 +1,110 @@
+# PROCESIO — HTML to Word (.docx) inside a process
+
+How to produce a real Word document from the same HTML that `Generate Document` turns into a
+PDF, and the platform facts that decide the design. The converter is
+[`assets/html2docx/html2docx.js`](assets/html2docx/html2docx.js), guarded by
+`tests/test_html2docx_asset.py`.
+
+## Why the obvious routes fail
+
+- **`Generate Document` has no Word output.** Its `Save document as` select offers exactly
+  `PDF` (value `1`) and `HTML` (value `2`). There is no DOCX option to switch to.
+- **Saving the HTML bytes as `.doc`/`.docx` does not work.** `String To Base64` -> `Base64 To
+  File` with a `.docx` name gives Word a file it either refuses (a `.docx` must be a zip) or
+  imports through its HTML importer (`.doc`). That importer ignores most class-based CSS from a
+  `<style>` block, so a document styled the way generated HTML usually is (classes, `colgroup`
+  widths in %, wrapper padding) comes out with wrong fonts, margins, table widths and spacing,
+  while the PDF of the same HTML looks right.
+- The PDF side is not a neutral reference either: the PDF renderer receives the HTML after a
+  sanitizer that drops the DOCTYPE (so it renders in **quirks mode**: tables reset their font),
+  uses **screen** CSS, ignores `@page`, and shrinks the page to fit. Match its layout rules, not
+  its pixels.
+
+## The working shape (verified live)
+
+```
+html (String) -> String To Base64 --\
+                                      >-- Join -> Node (converter) -> Base64 To File -> docx (File)
+htmlFile (File) -> File To Base64 --/
+```
+
+- Inject the HTML into the Node as **base64 inside double quotes** (`var HTML_B64 = "<%0%>";`).
+  Base64 has no quote, backslash, backtick or `${`, so it is the one string form that cannot
+  break or inject into the script. The converter decodes it.
+- **`String To Base64` encodes UTF-8.** A Romanian contract with diacritics converted through
+  the live process produced a `word/document.xml` byte-identical to a local run on the same
+  file.
+- Options travel as one **Json** input injected as `[<%1%>][0]`, which is `undefined` when the
+  caller sends nothing (a bare null injection is a syntax error, see
+  PROCESIO-NODE-CODE-NOTES.md).
+- The Node **returns the .docx as one base64 string** in `Single Result` (500 KB+ works) and
+  writes a JSON report with `console.log`, which lands in the Node's **`Stdout`** output
+  property (a string, with a trailing newline). A Node has no other second output.
+- A **rule `Decisional` with `IS_NOT_EMPTY` on a File variable** routes correctly: a file
+  goes to the first case, an unset file falls through to the next case.
+- **`Stop` accepts one input.** Wiring several branches (success, two `Throw`s) straight into it
+  fails backend validation with statusCode `383` "Action has too many input ports.". Converge
+  them on a `Join` first.
+- A 200-270 KB contract converts in about 0.2 s inside the Node; set `Timeout` well above that
+  anyway (180) for documents with many images.
+
+## What the converter does (so a change keeps the same rules)
+
+- Parses HTML, applies a browser default sheet, presentational attributes (`align`, `bgcolor`,
+  `border`, `cellpadding`, `width`, `<font>`), every `<style>` block and inline styles with
+  normal CSS precedence (specificity, order, `!important`). Media queries are evaluated as
+  **screen** at A4 width, like the PDF renderer; `@page` is still read from `@media print`
+  blocks, because that is where authors put page setup.
+- **Page margins** = `@page` margins (default 1 cm, the PDF renderer's) **plus** the horizontal
+  margin/padding of `body` and of a single wrapper element under it. Folding the wrapper into the
+  margins gives an editable Word document instead of every paragraph carrying a left indent.
+- **Line spacing:** a unitless CSS `line-height` L becomes Word "multiple" `L / f`, where `f` is
+  the font's normal line height (Arial and Times 1.149, Calibri 1.2207, ...). CSS 1.241 on Arial
+  is Word's 1.08, which is what HTML generated from a Word original carries.
+- **Tables:** fixed layout on a twips grid; widths from `<col>`, then cells, then a content
+  estimate; `%` widths and margins resolve against the containing content width; negative
+  `margin-left` becomes a negative table indent; `rowspan`/`colspan` become `vMerge`/`gridSpan`;
+  `thead` rows repeat as header rows; cell padding becomes per-cell margins.
+- Paragraph margins collapse the CSS way (max of adjacent margins), because Word adds spacing
+  after and before instead of collapsing them.
+- `page-break-before/after: always` -> `pageBreakBefore` (a 1 pt paragraph carries it in front
+  of a table); `page-break-inside: avoid` -> keep-with-next on every paragraph but the last and
+  `cantSplit` rows. An empty block with a height becomes an exact-height spacer.
+- Inline backgrounds that match a Word highlight colour (`#FFFF00` ...) become highlights, so
+  placeholders stay one click to clear; other colours become run shading.
+- Images: base64 data URIs (PNG, JPEG, GIF, BMP) are embedded with their CSS size. `https`
+  images are fetched only when the caller opts in with `fetchImages: true` AND the sandbox
+  allows `require('https')`; by default (and always inside the platform sandbox, which blocks
+  `require`) a remote image is left as its `alt` text and the report lists a warning. Opt-in is
+  the safe default on purpose: the fetch retrieves whatever URL the HTML names, so enabling it
+  on untrusted HTML where `require` resolves is a server-side-request-forgery vector.
+
+## Known limits
+
+Flex and grid lay out as stacked blocks, floats and absolute positioning stay in flow, inline
+SVG is not drawn, `::before`/`::after` content is ignored, and side-by-side `inline-block` boxes
+stack vertically. Write HTML meant for both PDF and Word with tables for side-by-side layout.
+The converter flags flex, grid, float and inline SVG in the report `warnings`, so the author
+sees why a layout stacked instead of guessing.
+
+## Updating the converter in a live process
+
+The Node `Code` is the asset file between a first-line `//` comment and this wrapper:
+
+```js
+var HTML_B64 = "<%0%>";          // bound to the html_b64 variable
+var OPTIONS = [<%1%>][0];        // bound to the options (Json) input
+var res = H2D.convert(HTML_B64, OPTIONS, true);
+function done(r) { try { console.log(JSON.stringify(r.report)); } catch (e) {} return r.base64; }
+return (res && typeof res.then === 'function') ? res.then(done) : done(res);
+```
+
+Rebuild the process with `process-edit` (the builder writes both the runtime and the designer
+copy of the code). Never write a `<%` sequence anywhere in the asset, comments included: the
+platform substitutes it textually. The test enforces this.
+
+## Verifying a result
+
+Open the generated file in real Word and export it to PDF, then compare page by page with a
+browser print of the same HTML (headless Chrome `--print-to-pdf`). A `.docx` that only passes a
+zip/XML check can still be one Word refuses or repairs.