procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/PROCESIO-NODE-CODE-NOTES.md

@@ -0,0 +1,279 @@
+# PROCESIO — Node `Code` interpolation safety, and the credential-free run-history actions
+
+Two hard-won build facts, generalized. Keep the specifics (datatype ids, action names,
+param shapes) — they are the knowledge, not incidental to one case.
+
+## 1. `<%N%>` substitution into a Node's `Code` is TEXT substitution, and only an OBJECT value is safe
+
+A Node `Code` parameter binds variables to `<%0%>`, `<%1%>`, … in a `variable` list
+(`[{id:N, variableId:…}]`); at run time each `<%N%>` is replaced **in the source text
+before parsing**. What the replacement text is depends on the variable's **datatype**, and
+the four contexts behave differently (measured, one hostile string `` IN${(6*7)}"q\Z `` in
+each):
+
+| how the value is written in the Code | a hostile STRING value | verdict |
+|---|---|---|
+| bare `const v = <%0%>;` | raw text → syntax error (the node fails) | unusable for strings |
+| double-quote `const v = "<%0%>";` | a `"` in the value closes the string → syntax error | UNSAFE |
+| **backtick `` const v = `<%0%>`; ``** | **`${…}` EXECUTES** (`${(6*7)}`→42); a backtick breaks the script | **UNSAFE — code injection** |
+| **Object/Json datatype, bare `const o = <%0%>;` then read `o.field`** | JSON-encoded by the platform → the value is a proper JS literal, everything escaped | **SAFE** |
+
+**So: a `"type":"string"` input spliced into a Code template is the injection signature.**
+`${…}` only fires inside backtick template literals, so backticks are the dangerous case,
+but double-quote and bare are not safe either (a quote/backslash/newline still breaks
+them). The **only** injection-safe transport is an **Object/Json** variable
+(datatype `0317bfee-b2f5-4bde-bfe8-121212121220`): the platform JSON-serialises it on
+substitution.
+
+**The fix ("structure transport"):** route scalar inputs through ONE Object input rather
+than N String inputs. Declare one Object variable (e.g. `sifParams`), have the form/caller
+populate its keys, and read `params.field` inside the node via bare Object injection. When
+converting an existing process, rewrite the consuming nodes to read from the Object,
+rebind their `Code` `variable` list to it, renumber the output placeholders, and **remove
+the old String inputs** (a leftover `isRequired:true` String input makes publish reject a
+run that omits it: `373 "Missing required input for variables: …"`). The values are
+unchanged, so a deterministic output stays byte-identical.
+
+⚠ **A null-valued injection is itself a defect.** When a bound variable is **null** at run
+time, `<%N%>` substitutes **empty text**: `const v = <%N%> || x;` becomes `const v = || x;`
+→ SyntaxError, which the platform **captures** (the instance still finishes status 50) and
+the node's output is null — a silent failure. Any `<%N%>` whose variable can be null
+(an optional output var, a file descriptor set on only one branch) must be written
+**`[<%N%>][0]`** — `[][0]` = `undefined` on a null injection, `[value][0]` = value
+otherwise. Read a node's error variable to catch this (`"Unexpected token '||'"` /
+`"Unexpected token ';'"`).
+
+## 2. A process can read its own workspace's run history in-flow, with NO credential
+
+Three `isProcesioAction` built-ins carry **zero credential parameters** (the Call API v1/v2/v3
+path needs a bound REST credential, which does not travel with a pack — avoid it):
+
+- **Get Recent Instances** (`actionId cf514e01-…`) — inputs `Page Number` + `Page Item Count`
+  (required Integers; 0 = all), optional `Select Process` (flow-list) / `Process Template Id`
+  / `Status type`; outputs `Result` and `Total Count`. ⚠ `Result` comes back as a **LIST of
+  run rows** (`{Id, Status, UpdatedOn}`, PascalCase), **carrying NO variable values** — the
+  outcome is per-instance. Read `Total Count`, not the row count (a short page reads like a
+  stable total).
+- **Count Recent Instances** — outputs `Process Instances Count` (Integer); optional process-id
+  list (empty = whole workspace) + `Status type`.
+- **Get Instance Outputs** (`actionId 98ab31ca-…`) — the per-run outcome. Needs `Select Process`
+  (flow-list = the target process id), **`InstanceId` (Guid datatype, NOT String — a String
+  var is rejected on save)**, and an `Output Variables` **process-outputs** mapping (the
+  selected process's output var → a local var). It wraps `GET /api/Projects/instances/{id}/output`.
+
+**Build recipe (compact builder):** the count outputs need `"type":"integer"` (`"number"`
+= Double, rejected `142 "Data type mismatch"`). `Get Recent Instances.Result` is one object
+var. Express `Get Instance Outputs` with a `subprocess` key:
+`{"action":"Get Instance Outputs","params":{"InstanceId":{"var":"topId"}},
+"subprocess":{"target":<pid>,"outputs":{"localVar":<subOutputVarId>}}}`, and type the
+`InstanceId` var as the Guid datatype via the builder's `"model":"0317bfee-b2f5-4bde-bfe8-121212121222"`
+escape hatch. This lets a form → process → native-actions topology list runs, count them,
+and show each run's summary with **no store, no credential, no foreign binding** — the
+property a distributable pack needs. The card's side of the contract is one deliberate
+OUTPUT-oriented variable (orientation 30) carrying the summary; `/status?getVariables`
+returns its value in `defaultValue` and `/output` at `result.instance.variable[<name>]`
+(NOT gated by `isArchived`). Proven end-to-end at UC7 E-164.
+
+## 3. Editing a live Node's `Code` in place: fix BOTH copies (runtime param AND designer customData)
+
+⚠ **A Node action carries the `Code` TWICE in the persisted flow**, and an in-place edit that touches
+only one ships a stale card. The two copies (confirmed on a live store-write card, 2026-09-02):
+
+- **`Flows[i].Actions[j].Parameters[k].Value`** — the RUNTIME copy. This is what the engine executes.
+- **`Flows[i].Actions[j].CustomData.configuration[*].settings[*].value`** — the DESIGNER-layer copy
+  (the "Code" setting the designer shows and re-materialises from).
+
+**Why it bites.** A binding-driven / spliced `put-projects` that rewrites only the runtime parameter
+(e.g. to push a corrected engine body) leaves the customData copy STALE. Consequences: (1) the standing
+card RUNS correctly (runtime wins at execution), so a happy-path run looks fine and hides the drift;
+(2) **`export` serialises the customData copy**, so the exported pack carries the OLD body — a handover
+pack that imports a stale card even though the source card ran the new one; (3) any designer re-save can
+re-materialise the runtime FROM the stale customData, silently reverting your fix.
+
+**The discipline.** When you edit a Node's `Code` on a live flow, replace it in **both** places, then
+read the flow back and assert BOTH carry the new body (grep a marker that only the new body has, and a
+marker only the old one had, on the runtime `Value` AND every `customData…settings…value`). Only then is
+the card — and its export — actually on the new code. This is the specific, mechanical form of the
+"read back, don't trust the write" rule (a `put:true` / HTTP 200 is not evidence the body changed, and it
+is certainly not evidence that BOTH copies changed). A full rebuild through `process-create` regenerates
+customData from the config and so avoids the split, but changes the flow id; editing in place (to keep a
+standing card's id) is exactly when you must fix both copies.
+
+## 4. A Node's `Code` can contain literal control characters, which `argv`-based editing cannot carry
+
+A Node body is stored as a plain string field, so it can hold **literal control characters** — in
+practice `\x00`, used as a composite-key separator because it cannot collide with real data:
+
+```js
+var key = r.SupplierID + "<0x00>" + r.CNCode;   // renders as a space in every terminal and diff
+```
+
+Nothing marks such a line as unusual: a terminal, the designer and most diff views all render `\x00`
+as a space. Two consequences for anyone editing a live body:
+
+- **`node-replace-text` (and any tool that shells out) fails if `--find` or `--replace` contains one.**
+  Python's `subprocess` raises `ValueError: embedded null character` and rejects the *whole* command,
+  so the error names no argument and points nowhere near the line responsible. `grep` likewise reports
+  `Binary file … matches` and prints nothing — pass `-a` to search a captured body.
+- **Never retype such a line.** Copying it by hand substitutes a space, and the code still runs: keys
+  simply stop matching, with no error at any layer.
+
+Editing around it, in order of preference:
+
+1. **Anchor on a NUL-free line.** Pick the nearest unique neighbouring line and insert before or after
+   it, instead of rewriting the line that carries the separator.
+2. **Write the separator as a source-level escape** — `"\u0000"` — so the argument you pass is entirely
+   printable while the running code still builds the byte-identical key.
+3. **Locate them before choosing an anchor**: capture the body (`node-params`), then print every line
+   where `'\x00' in line`. Do this first; it costs one read and removes the whole failure mode.
+
+Corollary for the code itself: keep per-record state **on the record object** (`obj._budget = …`)
+rather than in a side map keyed by the composite key — then no key has to be constructed, or typed,
+at all.
+
+As always, the edit must land on BOTH copies (§3): a NUL-free anchor is what makes `--expect 2`
+usable here.
+
+## 5. A `<%N%>` in your `--find` matches the RUNTIME layer only — expect 1, not 2
+
+§3 says an in-place `Code` edit must reach both copies. That is still true, but the expected hit
+count is **not always two**, and getting it wrong looks like a successful edit that never happened.
+
+The two layers store placeholders differently:
+
+| layer | path | how a bound variable appears |
+|---|---|---|
+| runtime | `parameters[…].value` | `var f = <%6%>;` — positional placeholder |
+| designer | `customData.configuration[…].settings[…].value` | `var f = 6161830e-…;` — the variable's **GUID** |
+
+So a `--find` that contains `<%N%>` can only ever match the runtime layer: `--expect 2` fails the
+assertion and — correctly — **writes nothing**. A find whose text has no placeholder matches both
+and gives the familiar `replacements=2 leaves=2`.
+
+- Placeholder in the find → `--expect 1` (plus `--allow-binding-change`, which the tool demands
+  for any find/replace touching a placeholder even when the placeholder multiset is unchanged).
+- No placeholder in the find → `--expect 2`.
+
+After a runtime-layer hit the tool **regenerates the designer layer from runtime**, translating each
+`<%N%>` back to its variable GUID, so both copies end up consistent from the single edit. Read back
+and confirm that rather than assuming it — the check costs one call and is the whole of §3.
+
+**A mismatched `--expect` reports the hit count it found, not an error.** Print the `put` field, not
+just `replacements`: `put: false` is the difference between "edited" and "declined to edit".
+
+**Never spell `<%N%>` out in prose inside the body.** Substitution is textual and does not respect
+comments, so a placeholder written in a `/* … */` explanation is injected like any other occurrence —
+it changes the binding footprint and can drop a value into the middle of your comment.
+
+## 6. Clearing `isRequired` does not make a File input optional — a native File action rejects null
+
+Making a File input genuinely optional takes **two** changes, and the flag is the lesser one.
+
+1. **The Code node** must survive the absent value. A bare raw placeholder on the right of an
+   assignment (`var f = <%6%>;`) becomes `var f = ;` — a SyntaxError that kills the node before any
+   of its own diagnostics can run. Guard it as `[<%6%>][0]`, which yields `undefined` when absent and
+   the object when present. (Quoted placeholders — `"<%1%>"` — are already safe: they collapse to `""`.)
+2. **Every upstream native action that consumes the file** must be branched around. A native
+   `File To Base64` fails the whole run with `Input file can't be null.` (status 40) — it has no
+   tolerant mode and no parameter that changes this. Clearing `isRequired` on its own therefore
+   converts a form that *blocks* the user into a run that *crashes* on them, which is strictly worse.
+
+So the structural fix is a branch — a Decisional on "is the file null", with the encode on one leg
+and an empty-string assignment to the base64 variable on the other — added via `process-edit`'s
+desired-state config (there is no `node-add`). Until that branch exists, **leave the flag required**:
+a required input is an honest constraint, an optional one that hard-fails is a defect.
+
+Generalises to any native action that takes a File: test the absent case before you advertise the
+input as optional.
+
+## 7. `validate` does NOT parse the Node body — syntax-check it yourself
+
+`node-replace-text` validates and flow-lints before it PUTs, and it will report `isValid: true` for a
+body containing a **syntax error**. The platform validator checks the flow graph and parameter
+shapes; it never parses the JavaScript. So a missing brace sails through validate, through the PUT,
+and through publish.
+
+At run time the node does not throw a catchable error — the body fails to compile, so the node's own
+top-level `try { OUT = run(); } catch` never executes and the node returns **null**. What you see is
+a downstream failure with a misleading message:
+
+```
+node: Write Workbook | type: Base64 To File
+msg: Base64 string can't be null.
+```
+
+The named node is fine. The producer three steps upstream is the one that failed, silently. Read the
+producer's output variable: `recon: null` with every text pane also `null` is the signature.
+
+**Always syntax-check after editing a body**, with the placeholders neutralised so a real parser can
+read it:
+
+```bash
+python scripts/run-tool.py procesio node-params --id <flow> --node <node> > nc.json
+# extract the body, then:  src = re.sub(r'<%\d+%>', '0', body)
+# wrap it in a function so `return` at top level is legal, and:
+node --check nc.js
+```
+
+`node --check` reports the line. Do this before the run, not after: a run costs minutes and points
+at the wrong node.
+
+### The specific way this happens: a line-range FIND swallows an enclosing brace
+
+Extracting `--find` as a slice of lines (`L[start:end]`) is convenient and dangerous. If the slice's
+last line is a `}` that closes an **enclosing** block rather than one opened inside the slice, the
+replacement must re-emit it. It is invisible in review because both the FIND and the REPLACE look
+internally balanced:
+
+```js
+if (outer) {                 // opened BEFORE the slice
+    var x = f();             // <-- slice starts here
+    if (inner) { ... }
+  }                          // <-- slice ends here: this closes OUTER, not inner
+```
+
+Prefer a FIND anchored on syntactically complete text. When a line range is unavoidable, count braces
+across the FIND and the REPLACE and require the deltas to match before writing.
+
+## 8. Inserting an action into a live flow: two edits, and a casing trap
+
+`node-insert` exists now. Two things make a hand-rolled version go wrong, and both fail *silently*
+— the flow still validates.
+
+**Ports live on the SOURCE action.** An edge is `{sourceId, destinationId}` stored on the node it
+leaves. So inserting X between A and B is two edits, not one: give X a port to B, then repoint A's
+port at X. Do only the first and X is unreachable; do only the second and everything after A is
+orphaned. Neither is a validation error.
+
+**The DTO builder emits PascalCase; a live flow is camelCase.** `_action_node()` returns
+`{Id, FlowId, Ports, Parameters, CustomData}` — the CREATE shape — while `GET /api/Projects/{id}`
+returns `{id, flowId, ports, parameters, customData}`. The API accepts both, so splicing one into
+the other is accepted and then renders inconsistently in the designer. Convert with
+`nodeparam.to_live_action()`, which also lowercases each `parameters` row
+(`TabPropertyId` → `tabPropertyId`).
+
+Refused rather than guessed: an anchor with more than one outgoing port. Which branch the new node
+belongs on is a design decision.
+
+**Related, and the reason this tool had to exist:** `process-edit` is a desired-state rebuild, so
+adding one action to a 22-node flow through it means re-expressing the whole flow — including a
+70 KB Node body — as config. `read-flow-graph` is an offline reader and does not produce that
+config, so there is no round-trip.
+
+## A `<%N%>` placeholder is injected RAW - quote it yourself for a string
+
+The scripting actions substitute the value into the source text before it is parsed, so the
+template has to supply the quotes for anything that is not already valid JavaScript on its own.
+A list or object arrives as JSON and needs none; a **string does**:
+
+```js
+const isoDate = String('<%0%>' || '');   // right
+const isoDate = String(<%0%> || '');     // wrong
+```
+
+Unquoted, `2026-09-24` is parsed as arithmetic and silently becomes `1993`, and a date-shaped
+string is the common case. There is no error: the script runs, the value is quietly wrong, and
+the step returns an empty result. Cost an hour on a slot generator that answered "no times
+available" for every day. The same applies to any free text - a name with an apostrophe in it
+will end the string early, so a value that can contain quotes belongs in a JSON-serialised
+object placeholder rather than an interpolated string.

procesio_cli/tools/procesio/PROCESIO-NODE-MODULE-WHITELIST.md

@@ -0,0 +1,113 @@
+# PROCESIO `Node` (NodeJS) sandbox — module whitelist & I/O mechanics
+
+What the platform's **`Node`** action (`e0fc20c3-e333-554c-a062-f64894db51dd`) can and
+cannot `require`, how data enters and leaves it, and the consequences for building file
+outputs. Probed live against a NodeJS `Node` action (`Timeout` 60–300; top-level `return`
+sets the result). Reuse these facts before designing any Node-heavy flow (grouping,
+dedupe, report/file generation) — they decide the whole architecture.
+
+## Module availability — the sandbox is heavily locked down
+
+Probed `require()` for each; **every external npm module failed** with
+`Cannot find module '<name>'`:
+
+| Probed | Result |
+|---|---|
+| `xlsx`, `exceljs`, `xlsx-populate`, `write-excel-file`, `node-xlsx` | ❌ not installed |
+| `fast-xml-parser`, `xmlbuilder2` | ❌ not installed |
+| `jszip`, `pako` | ❌ not installed |
+
+Builtins are almost all blocked. Two are present:
+
+| Builtin | `fs` | `zlib` | `buffer` | `child_process` | `os` | `path` | `crypto` | `https` |
+|---|---|---|---|---|---|---|---|---|
+| Available | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
+
+`process` is also restricted — reading `process.version` throws
+`Cannot read properties of null (reading 'version')`. **Rule: assume a Node action has the
+JS language plus `crypto` and `https`, and nothing else until probed.** No filesystem, no
+`Buffer`, no compression, no shelling out, no npm. Guard any `process`/global reference in a
+`try/catch` or it aborts the whole action.
+
+> **CORRECTED 31/08/2026.** This file previously read *"only `crypto` is present"* and
+> *"assume a Node action has the JS language + `crypto` only"*, while
+> [PROCESIO-API-NOTES.md](PROCESIO-API-NOTES.md) recorded, from its own live probe, that
+> **`require('https')` also works** and that an async `return new Promise(...)` resolves.
+> Both were live-probe records, neither cited the other, and the narrower falsified rule sat
+> in the file a reader opens to look module availability up. **The lesson generalises: a
+> probe result states what was probed, not what exists.** `https` was never in this file's
+> probe set, so its absence from the table was an untested gap being read as a negative
+> result. When a note says "only X is present", record the probe set beside it.
+
+## Consequence for Excel: build the .xlsx in pure JS (no library)
+
+Because there is **no `Buffer`/`zlib`/xlsx lib**, and because the catalogue's `XLS To XLSX`
+converter **rejects** SpreadsheetML 2003 (verbatim: *"The supplied data appears to be a raw
+XML file. Formats such as Office 2003 XML are not supported"*), the only way to emit a
+genuine **single-file, multi-sheet** `.xlsx` is to author the OOXML package by hand inside
+the Node action:
+
+- Build each part's XML as a string (`[Content_Types].xml`, `_rels/.rels`,
+  `xl/workbook.xml`, `xl/_rels/workbook.xml.rels`, `xl/worksheets/sheetN.xml`), using
+  `t="inlineStr"` cells so no `sharedStrings`/`styles` parts are needed.
+- Pack them into a **ZIP with STORED (method 0, uncompressed) entries** — a stored ZIP
+  needs only CRC-32 (implementable as a pure-JS table) and correct local-header /
+  central-directory / EOCD byte layout; **no compression, so `zlib` is not required**.
+- UTF-8-encode strings by hand (no `Buffer`), CRC-32 by hand, base64-encode the byte array
+  by hand, then feed that base64 to the catalogue action **`Base64 To File`**
+  (`6fad5599-…`) → a real `.xlsx` File (MIME
+  `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`).
+
+This was verified end to end (openpyxl re-opened the result: correct sheet names, string
+headers, numeric cells typed as numbers). It is the **preferred multi-sheet path** — one
+file, real sheets, only two actions (`Node` + `Base64 To File`) — and beats the fallbacks:
+`Export To XLSX` writes **one sheet from a list**; `Create Workbook`/`Insert Sheet` create
+only **empty** sheets (no catalogue action writes data into an existing sheet). A reusable
+pure-JS writer (`AAT_XLSX.build(sheets)`) lives with the VAT-reconciliation build assets.
+
+## How data ENTERS a Node — `<%N%>` injection, materialised
+
+A Node reads flow variables only through **`<%N%>` placeholders in the `Code`** (bind the
+`Code` param with `{template, vars:[...]}`; index is global across the action's params):
+
+- A **list/object** variable injects as its **actual JSON value** — `var rows = <%0%>;`
+  yields the real array/object (verified: a parsed CSV list arrived as a JS array of
+  objects). So one Node can consume several upstream datasets at once.
+- A **string** variable injects as a **bare, unquoted token** — you must quote it yourself:
+  `var p = "<%1%>";`. Consequently a caller-controlled string is injected into source
+  before your code runs; treat it as untrusted (a stray `"` breaks the script). Prefer
+  passing untrusted text inside a JSON list/object channel (JSON-escaped) rather than as a
+  raw quoted scalar.
+- An **optional number** with no value injects as **nothing** (`var t = <%5%>;` →
+  syntax error). Give optional numeric inputs a default, or don't inject them.
+
+## How data LEAVES a Node, and why you often need extractor Nodes
+
+A Node has exactly three output props: **`Single Result`** (scalar/object, raw — no
+wrapper), **`List Result`** (list), **`Error`** (string; note scripting errors are also
+reported here, they do **not** take the error port). `Javascript` instead wraps as
+`{result: v}` — prefer **`Node`** for clean typed output.
+
+**Attribute-path binding does NOT work on a generic Json/Object variable.** Binding a
+downstream param to `{var:"bundle", path:["reportHtml"]}` fails BE validation with
+`Error converting value "reportHtml" to type 'System.Guid'` — the platform expects the
+attribute to be a **DataModel attribute GUID**, which a schemaless Json object doesn't
+have. So you cannot fan a single Node's object result out to several consumers by sub-path.
+Two ways around it:
+
+1. **Extractor Nodes** (used here): the producing Node returns the whole bundle to a
+   process var; a tiny Node per consumer injects the bundle and `return`s the one field it
+   needs as a clean `Single Result`, which binds directly. Cheap and reliable; keep large
+   strings (HTML, base64) out of the re-injected bundle so they aren't serialised N times.
+2. Define a **DataModel** (`datatype-create`) for the bundle so its attributes have GUIDs,
+   then `{var,path}` binding resolves.
+
+## CSV reading — `Read Range from CSV`, not `File To JSON`
+
+`File To JSON` (`fd9d7d38-…`) **rejects non-JSON**: `File extension should be '.json',
+found => .csv`. Use **`Read Range from CSV`** (`9c9cc774-…`): params `CSV file` (file),
+`Range` (e.g. `A1:Z1000` — clips to actual data, no empty padding), `Values` (output). It
+returns a **list of row objects keyed by column letter** (`{A,B,C,D,…}`), **row 0 is the
+header row**, and numeric-looking cells arrive as **JS numbers**. Read the header row to map
+column-name → letter so the flow is robust to column reordering and can detect optional
+columns.

procesio_cli/tools/procesio/PROCESIO-PYTHON-ACTION-NOTES.md

@@ -0,0 +1,165 @@
+# PROCESIO `Python` scripting action — libraries, I/O, and the model problem
+
+What the platform documents about the **Python** scripting action, and the traps that
+follow from it. Everything here is **vendor-documented** unless a line says otherwise;
+none of it has been executed against a live instance from this framework. Companion notes:
+[`PROCESIO-NODE-MODULE-WHITELIST.md`](PROCESIO-NODE-MODULE-WHITELIST.md) (probed live) and
+[`PROCESIO-CUSTOM-ACTION-NOTES.md`](PROCESIO-CUSTOM-ACTION-NOTES.md).
+
+> ## ⚠ A scripting action that returns an ARRAY must bind "List Result"
+>
+> Verified live on a `Node` action, 31/08/2026; the property pair is the same
+> shape on the scripting actions generally.
+>
+> A scripting action exposes **two** result properties, and they are not
+> interchangeable:
+>
+> | property | binds |
+> |---|---|
+> | `Single Result` | a scalar or an object |
+> | `List Result` | an **array** |
+>
+> Returning an array while bound to `Single Result` stores **null**. There is no
+> error on the action, no error variable is set, and the instance still reaches
+> status 50 — the run looks completely healthy while the payload is gone. A
+> sibling action publishing a COUNT from the same object succeeds, which makes it
+> worse: the run reports "3 entities" beside a null entity list.
+>
+> The receiving variable must ALSO be declared `isList: true`. Both halves are
+> required and each fails the same silent way on its own.
+>
+> **Diagnosing it from downstream.** When a later action reports a JavaScript
+> parse error such as `Unexpected token ';'`, that is a NULL upstream variable,
+> not a syntax problem. `<%N%>` is a TEXTUAL substitution into the script source,
+> so a null variable interpolates to nothing and what the engine compiles is
+> `var o = ;`. Read that error as "the variable upstream is empty" and look at
+> what wrote it. By the same mechanism a raw string interpolates UNQUOTED and
+> yields `Unexpected identifier` — which is why a string input has to ride inside
+> an object wrapper (`{"v": "..."}`) and be unwrapped in the script.
+
+## Preinstalled libraries
+
+`matplotlib 3.7.0`, `beautifulsoup4 4.12.0`, `scipy 1.10.1`, `PyPDF2 3.0.1`,
+`pandas 2.0.3`, `pdfplumber 0.11.4`, `spacy 3.8.4`, `staticmap 0.5.7`, `pillow 12.1.1`.
+
+**The same documentation page contradicts this list.** An earlier callout on it says the
+Python action "has a list of available libraries to be used: JSON, Base64". Treat the
+nine-package table as the current statement and the callout as stale, and **verify by
+importing before designing against any of them** — the two readings differ by everything.
+
+**No route to add a library is documented**, and `pip install` appears nowhere in the
+documentation corpus. Assume the set is closed.
+
+## What is NOT documented — check before relying on any of it
+
+- **The Python version.** Stated nowhere. This matters more than it looks: library and
+  model wheels pin interpreter and framework ranges, so an unknown interpreter cannot be
+  reconciled with a pinned dependency on paper.
+- **Network access.** Never mentioned, and no HTTP client is on the list (no `requests`,
+  no `httpx`). Do not assume a script can reach out.
+- **A writable path.** The docs say plainly that files cannot be added in a Python script.
+  Nothing describes a temp directory, a working directory, or a cache.
+- **Persistence between invocations.** Nothing survives, as far as the documentation says
+  anything at all.
+- **Timeout, memory ceiling, payload size.** None documented. The Node action documents a
+  timeout; the Python action documents none.
+
+## I/O mechanics — two traps
+
+**Output is whatever the script PRINTS**, wrapped as `{"result": ...}`. To get at the
+value, follow the action with a **JSON Mapper** using query `$.result`. Design for that
+extra hop rather than binding the Python output directly.
+
+**⚠ Input is textual substitution into the source before execution.** The documentation is
+explicit: PROCESIO "replaces the variable with the value of the variable and then utilizes
+it within the code". So `x = <%myvar%>` pastes the raw value into the script.
+
+The consequence is the same one recorded for the Node action, and it bites hardest exactly
+where scripting looks most attractive: **any script whose input is untrusted, multi-line,
+or quote-bearing text is unsafe through a raw scalar substitution.** A stray quote breaks
+the script; a crafted string executes. **Pass untrusted text through a JSON or object
+channel** so it arrives escaped, and treat even that as unverified until measured.
+
+## Working with files — the base64 bridge
+
+A Python script cannot open a file. The documented mechanism is a bridge through process
+variables:
+
+```
+File variable → [File to BASE64] → string → <%var%> → Python script
+Python string result → [Base64 to File] → File variable
+```
+
+That is the platform's intended file channel for **every** scripting action, not just
+Python. It is not a file system, and it makes the file content transit the script's source
+text, so the substitution trap above applies to it directly.
+
+## ⚠ `spacy` is on the list; a spacy MODEL is not
+
+This is the trap worth writing down, because "the NLP library is available" reads as a
+capability and is not one.
+
+- **`spacy` ships no model.** `import spacy` succeeds and `spacy.blank("en")` gives a
+  tokeniser whose `.ents` is empty forever. **A library without a model does no NER.**
+- **Models are separate packages** and none is documented as preinstalled. Loading one at
+  runtime would need **network** (undocumented) and **a writable cache** (documented
+  absent), then would need to survive between invocations (undocumented). `spacy.load`
+  takes a directory path, so bytes arriving over the base64 bridge still need somewhere to
+  land.
+- Sizes are real: `en_core_web_sm` 3.8.0 is **12.8 MB**, `xx_ent_wiki_sm` 3.8.0 is
+  **11.1 MB** (measured from the wheels). A model re-fetched per invocation is a cost line,
+  not a detector.
+
+**Before promising NER on this route, execute exactly one thing: `spacy.load` on a
+plausible model name.** Everything else is downstream of that answer.
+
+### Model facts worth having to hand, all read from the wheels' own metadata
+
+| Model | Licence | Languages | NER labels |
+|---|---|---|---|
+| `en_core_web_sm` 3.8.0 | **MIT** (weights) | **English only** | 18: CARDINAL, DATE, EVENT, FAC, GPE, LANGUAGE, LAW, LOC, MONEY, NORP, ORDINAL, ORG, PERCENT, PERSON, PRODUCT, QUANTITY, TIME, WORK_OF_ART |
+| `xx_ent_wiki_sm` 3.8.0 | **MIT** (weights) | multilingual, **WikiNER languages — European, no Arabic** | **4**: LOC, MISC, ORG, PER |
+
+**Package licence and training provenance are different questions, and a compliance review
+will ask about both.** `en_core_web_sm` ships MIT weights and a `LICENSES_SOURCES` file
+recording that its training corpus, OntoNotes 5, is **"commercial (licensed by
+Explosion)"**. `xx_ent_wiki_sm` is trained on WikiNER under **CC BY 4.0**. Read the shipped
+licence files, not the package licence alone.
+
+**Other NER stacks are absent**: no `transformers`, no `torch`, no `gliner`, no `stanza`,
+no `flair`. Any design that assumed a transformer-based or zero-shot detector inside the
+Python action needs a different home for it.
+
+## Where the compute runs, and why it matters for sizing
+
+A Python action executes **inside the Execution Environment**. An external detector behind
+a Call API is I/O wait, which at least raises the question of releasing the EE while it
+waits. **In-action inference never raises that question: the EE is held for the whole
+computation.** So moving model work into a Python action trades an integration for
+occupancy, and the fleet sizing has to be recomputed rather than inherited.
+
+> ## ⚠ An object-typed input reports its shape as `{}` — and a bare string reaches the API as an empty body
+>
+> Verified live on a `Node`-based flow driven through `run-process`.
+>
+> `get-process-payload` is the authority on what a process expects, and it
+> distinguishes the two cases: a string-typed input renders as `""`, an
+> object-typed one as `{}`. An input showing `{}` is **not** a string variable,
+> whatever its name suggests, and the scripts downstream will unwrap it (the
+> convention here is `{"v": "<the string>"}` unwrapped as `text.v`). Passing the
+> bare string instead interpolates unquoted into the `<%N%>` textual
+> substitution and the node throws.
+>
+> **Why this is worth a note rather than a shrug: the failure arrives as a
+> plausible success.** Every node in the chain throws, so the variable feeding
+> the `Call API` body is null, so the platform posts an **empty body** — and the
+> remote service answers **200**. The instance reaches status 50. Read from the
+> status alone, the run is indistinguishable from a document in which the
+> detector correctly found nothing. The tell is in the response body, where a
+> well-built service says so (`warnings: ["empty input"]`, zero chunks). Read
+> the body, not the status, and check an early-stage variable — a null where a
+> local computation should have produced a value means the input never bound.
+>
+> The same trap applies to any required object input: a script that validates
+> its config (`if (!cfg || !cfg.recognisers) throw`) takes the whole chain down
+> when the caller omits it, and the run still reports as completed.