procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/agents/procesio/IMPLEMENTATION-PATTERNS/01-PROCESSES.md

@@ -0,0 +1,230 @@
+# Process-building patterns (generalized)
+
+These patterns were distilled from a production PROCESIO workspace (form-driven request intake,
+agent review, multi-party e-signing). They contain no client-specific values. Each entry gives the
+pattern, the problem, the mechanics, when to use it and its pitfalls. **Refines** marks an entry that
+sharpens or corrects a rule in `agents/procesio/PROCESIO-BEST-PRACTICES.md` (BP) or
+`PROCESIO-BUILD-AND-TEST-PLAYBOOK.md` (PB).
+
+---
+
+## P1. Dual outcome flags for form bindings (`e_ok` + `e_not_ok`)
+- **Problem:** a form output binding cannot negate a boolean, yet a result usually has to show one
+  element and hide another.
+- **Mechanics:** declare two Boolean outputs with pessimistic defaults (`e_ok=false`,
+  `e_not_ok=true`). One Map Data at the very end of the happy path flips both. The form binds
+  `successPanel.visible ← e_ok` and `inputPanel.visible ← e_not_ok`. Any early exit (error port, empty
+  guard) leaves the defaults, so the UI shows the "not ok" state automatically.
+- **When:** every process a form calls to decide visibility.
+- **Pitfalls:** optimistic defaults (`e_ok=true`) turn every crash into a false success. Keep one
+  casing for boolean literals (`true`, not `True`). Inside JSON results, don't switch the name to
+  `e_notOk`.
+- **Refines BP §9 / §5:** this is the cheapest way to surface failure to the user without extra calls.
+
+## P2. Render display blocks server-side as one inline-styled HTML string
+- **Problem:** status cards, dashboards, receipts and error banners need rich layout, but forms only
+  bind scalars.
+- **Mechanics:** a Node builds one root `<div>` with **inline styles only** (no `<style>`, no classes,
+  no JS), SVG icons inline, a palette constant object and `escapeHtml` on every value, then
+  `return html`. Bind it to `Paragraph.label`. For static messages a Map Data literal is enough.
+- **When:** any read-only visual summary. The same builder can feed Generate Document for a PDF.
+- **Pitfalls:** for HTML→PDF use tables + SVG, not flex/grid. Escape `'` too (`&#39;`) so the HTML
+  can later be stored through an `N'…'` SQL literal. Never let the node return null: render the error
+  into the HTML instead.
+
+## P3. Selector feeds as `{label, value}` lists
+- **Problem:** select and dropdown controls need `sourceValue` in a fixed shape. DB rows don't have
+  that shape.
+- **Mechanics:** one query per list, then one Node:
+  `(Array.isArray(rows)?rows:[]).map(r=>({label:r.X, value:r.X}))`. Put all lists for one form step
+  in **one** "render" process that returns every list plus the classification flags, so a single
+  click fills the whole step.
+- **When:** any form step with more than one data-driven selector.
+- **Pitfalls:** one Node per list is copy-paste. Write one Node that maps a dictionary of result
+  lists, or one SQL that returns every list as a JSON column. That also meets BP §10 (fewer actions).
+
+## P4. Whole-form-in, SPEC-driven reshaping server-side
+- **Problem:** form element names change between form versions (`SelectN` / `InputN`, renamed ids).
+  Mapping in the form is brittle and spread across many places.
+- **Mechanics:** pass the whole form instance (`instance / flow / fields`) as one JSON input. A single
+  Node holds a declarative SPEC object (`target.path: "Element.value"`) plus directives for the hard
+  cases:
+  - first available source among renamed elements
+  - repeating rows
+  - a value taken from the active branch of a cascading selector
+  - a value derived from section visibility
+
+  It also records `warnings[]`, a `SCRIPT_VERSION` marker, and `e_ok/errorMessage` inside a
+  try/catch.
+- **When:** any form with more than about 20 fields that feeds a DB or document.
+- **Pitfalls:**
+  - Keep exactly one copy of the engine (a Utils process). Forking it per flow produces divergent
+    versions.
+  - An automatic `SelectN`↔`InputN` fallback must be disabled where the twin id exists with a
+    different meaning.
+  - Inactive branches keep stale values, so read only from the branch the controlling selector
+    points to.
+
+## P5. Server-owned identity: overwrite the client-supplied key
+- **Problem:** a form can send any id. The primary key must come from the server.
+- **Mechanics:** right after reshaping, run Generate GUID **into the id attribute of the form object**
+  (Generate GUID can target an attribute path), then persist.
+- **When:** every create/submit from a public or guest form.
+- **Pitfalls:** return the generated id to the form (receipt number) so later steps (signature, file
+  uploads) are keyed to the same record.
+
+## P6. Validate in the stored procedure, persist the messages, then Throw
+- **Problem:** business validation spread across Decisionals is slow and hard to keep in sync with
+  the DB.
+- **Mechanics:** a single `EXEC <schema>.usp_…_Save @json` validates and writes in one transaction and
+  returns a status row: `e_ok`, the generated ids, and one row per validation message on failure. The
+  process branches on `e_ok`:
+  - failure: For Each message → insert into a validation-log table keyed by the request id →
+    `Throw` with a short message
+  - success: continue with side effects (files, documents, notifications)
+- **When:** multi-table inserts from one form submit.
+- **Pitfalls:**
+  - The SP commit is not atomic with the later side effects, so design for resume and make the
+    submit idempotent (dedupe key).
+  - Ids for branches that don't apply come back as the all-zero GUID. Branch on "non-empty AND not
+    the zero GUID".
+- **Refines BP §2 (idempotency) and §8.**
+
+## P7. SQL values: bind, or at minimum escape in a Node first
+- **Problem:** Execute Query text with `'{{var}}'` breaks on the first apostrophe in a name and is
+  injectable. It is worst when the value comes from a URL parameter.
+- **Mechanics:**
+  - Preferred (BP §8): parameter binding.
+  - If a whole JSON object must be passed as one string, run a Node first:
+    `return { json_sql: JSON.stringify(obj).replace(/'/g,"''") }` and inject that into `N'…'`.
+  - Validate tokens and ids taken from URLs as GUIDs before they reach SQL.
+- **When:** always.
+- **Pitfalls:** escaping is easy to forget on the next process that copies the pattern (seen: one
+  submit path escaped, its sibling did not). Treat an unbound interpolation of user input as a defect
+  in review.
+- **Refines BP §8:** adds the JSON-payload-to-SP case and the "URL-sourced value" severity.
+
+## P8. Guarded state transitions, then notify
+- **Problem:** "accept" or "deny" buttons can be clicked twice or on stale data.
+- **Mechanics:** `UPDATE … SET status='<next>' WHERE id=@id AND status='<expected>'`, check the
+  affected rows (or re-select), and only then send the e-mail. Flip `e_ok` only on a real transition.
+- **When:** every workflow status change.
+- **Pitfalls:** e-mailing before the guarded update notifies the customer about a transition that
+  never happened. A disabled status-update node leaves the item in the queue while the customer
+  believes it is closed. Keep status names in one place (lookup table or constants), not as literals
+  in every query.
+
+## P9. One click, one orchestrating process
+- **Problem:** attaching several async RUN_PROCESS actions to one button causes races (a later status
+  overwritten by an earlier one, a refresh that reads before the writes).
+- **Mechanics:** one process runs the steps in order (update → notify → re-read) and returns
+  everything the form needs. Use **Trigger Subprocess** only for side effects the user must not wait
+  for (e.g. notifying staff).
+- **When:** any button whose steps depend on each other.
+- **Pitfalls:** fire-and-forget hides failures. Log or flag them somewhere readable.
+- **Refines BP §9:** parallel async calls feel fast but are only safe when independent.
+
+## P10. Tokenised signer links through hash-routed form URLs
+- **Problem:** external signers need a personal link to one form page with their context.
+- **Mechanics:**
+  - One shared request id plus a unique per-signer token column.
+  - Link = `https://<forms-host>/forms/<formId>#<pageId>?req_id=<token>`. The parameter sits **after
+    the `#`** because the form uses hash routing.
+  - Page load calls a "verify token" process: look up by token → documents + flags.
+  - Signing calls a "sign by token" process: store the signature, `status='signed'`.
+  - Status lifecycle: created → sent → signed → submitted (countersign).
+- **When:** multi-party approval or signature without accounts.
+- **Pitfalls:**
+  - The token is a bearer credential. Give it an expiry and one-time use, and never put it into SQL
+    unbound.
+  - Build the base URL from one setting. A literal copied into several e-mail templates and code
+    nodes drifts when the form is republished.
+- **Refines BP "pre-fill controls from URL query params":** the hash-routing placement and the
+  security caveats.
+
+## P11. Business-day windows computed in code, with the calendar in Python
+- **Problem:** a date picker must allow only dates that give staff N working days, bounded by the
+  validity of the current offer period.
+- **Mechanics:**
+  - Python (has `zoneinfo`, `calendar`) prints the month's days
+    `{zi, data, ziuaSaptamanii, esteWeekend}` for the current and the target month.
+  - A Node merges both calendars into one sorted timeline keyed by date, counts the Nth working day
+    strictly after today, and returns `YYYY-MM-DDT00:00:00Z` or `""` when it falls past the period
+    end.
+  - The form binds min, max and default of the date input. An empty result swaps in an HTML "period
+    closed" banner (P2).
+- **When:** any "earliest allowed date" rule.
+- **Pitfalls:**
+  - Use the business's real timezone id.
+  - Include public holidays, not just weekends.
+  - Compare dates as `YYYY-MM-DD` strings or regex parts, not `new Date()` local getters (they shift
+    around midnight UTC).
+  - Put N and the timezone in one setting.
+
+## P12. Python action output is always `{"result": …}`
+- **Problem:** a Python action's `print(x)` arrives as `{"result": "<x as string>"}`, sometimes
+  double-encoded.
+- **Mechanics:** in the consuming Node, unwrap repeatedly: if string → `JSON.parse`; if object with
+  `result` → take `.result`; stop after about 5 levels. Or read `result` with Extract Objects when the
+  value is flat.
+- **When:** every Python → JS hand-off.
+- **Pitfalls:** interpolate strings into Python inside quotes (`'''{{v}}'''`). The value is injected
+  raw.
+
+## P13. Same script offline and in the platform
+- **Problem:** big code nodes (renderers, parsers) are hard to debug inside the designer.
+- **Mechanics:** write the node as a standalone file with a `LOCAL: node preview.js payload.json`
+  header. Treat an unreplaced placeholder (`/^<%[^%]*%>$/`) as empty, so the same text runs with
+  sample JSON locally and with bound variables in PROCESIO. Add a `SCRIPT_VERSION` constant to the
+  output.
+- **When:** any node over about 100 lines.
+- **Pitfalls:** placeholder-tolerance also hides a variable that was **never bound** (a literal
+  `<%name%>` left in the pasted code). After pasting, check that every placeholder became a bound
+  variable.
+
+## P14. Layout-tolerant spreadsheet parsing by label
+- **Problem:** tariff or price sheets from third parties move rows and columns between editions.
+- **Mechanics:**
+  - Read Range a generous block.
+  - A Node converts whatever shape comes back into a 2-D grid (array of arrays, row objects keyed by
+    letter or number, or a wrapper object).
+  - Locate blocks by label prefix (`findCell(grid,"total taxe")`) and read the values to the right.
+  - Parse numbers tolerantly (`"35,34 (note)"` → `35.34` + note).
+  - Emit a clean JSON document and pass it to one import SP.
+- **When:** any inbound Excel from outside your control, especially via webhook.
+- **Pitfalls:** keep the Read Range bounds and the comments in sync, or let the parser find the used
+  range. Protect the webhook with a header key that is compared to a value stored outside the process.
+
+## P15. File-to-PDF normaliser via template placeholder swap
+- **Problem:** uploads arrive as PDF or image, and downstream needs a PDF.
+- **Mechanics:** if the MIME type is already `application/pdf`, pass it through. Otherwise:
+  File To Base64 → render an HTML template containing a placeholder base64 image to an HTML string →
+  Replace the placeholder base64 with the upload's base64 → Generate Document from that HTML.
+- **When:** ID cards, invoices, any user-uploaded proof.
+- **Pitfalls:** non-image, non-PDF files (docx, heic) produce a broken image, so whitelist the MIME
+  types. Very large base64 values vanish when injected into Node code (BP field learning 3), which is
+  why the swap happens in Replace, not in JS.
+
+## P16. Shared-library hygiene for Utils
+- **Problem:** helpers get copy-pasted into node after node: label/value mapper, first-row field
+  extractor, date formatter, HTML helpers, e-mail shell, entity load chain.
+- **Mechanics:** anything pasted twice becomes a `Utils/ …` process with a typed contract, or one
+  multi-purpose Node that takes a dictionary of inputs. An identical load chain in three processes
+  becomes one "load aggregate by id" subprocess. Company contact and legal blocks, URLs, timezones and
+  lead times come from a single settings source.
+- **When:** at the second copy.
+- **Pitfalls:**
+  - Destructive admin utilities (bulk DELETE) do not belong in the production library.
+  - Empty stubs and disabled nodes should be deleted before handover.
+  - Two processes with the same title make subprocess binding ambiguous. Titles must be unique.
+- **Refines BP §2 "Centralize parameters" / "Modularize"** with concrete extraction triggers.
+
+## P17. Every Decisional needs a Default that reports
+- **Problem:** a Decisional with only positive cases dead-ends when no case matches. The run ends
+  with default outputs and the form cannot tell "no data" from "broken".
+- **Mechanics:** always wire a Default to a Map Data that sets `e_not_ok` plus a readable error
+  (text or HTML banner), then route it to the common Join and the single Stop.
+- **When:** every Decisional, especially classifiers (type A/B, energy X/Y, accept/deny).
+- **Pitfalls:** error-port branches that go straight to a bare Stop have the same problem. Prefer
+  "set error → Join → Stop".
+- **Refines BP §5.**

procesio_cli/agents/procesio/IMPLEMENTATION-PATTERNS/02-FORMS.md

@@ -0,0 +1,287 @@
+# Form patterns: generalized techniques (PROCESIO forms ↔ processes)
+
+These patterns were distilled from a production multi-step form workspace. Only reusable mechanics
+are kept here: no client, id or business value. Each pattern says how it relates to
+`tools/procesio/FORM-DEV-GUIDE/`: **NEW** (not covered), **REFINES** (adds to or corrects a
+section) or **CONFIRMS+** (covered, plus a field-tested detail).
+
+---
+
+## P1. Hidden status field as a JS → no-code bridge — NEW
+- **Problem.** Validation logic lives in JavaScript, but the reaction (show a button, lock fields,
+  reveal a step) is easiest to express as MAP_FORM_DATA conditions. A JS block cannot stop or steer
+  the rest of an event chain.
+- **Mechanics.** Add a number-input per step (`validation-of-<step>`) and hide it with CSS
+  (`display:none` on the control and, through `:has()`, on its wrapper). The JS block, placed before
+  the MAP blocks in the same click chain, computes pass or fail and writes `"1"` / `"0"` using the
+  **native value setter** (`Object.getOwnPropertyDescriptor(HTMLInputElement.prototype,'value').set.call(input, v)`)
+  followed by `input`, `change` and `blur` events. The native setter plus events is what makes Vue's
+  `v-model` take the value. The next events are `MAP_FORM_DATA when validation-of-<step>.value EQUALS 1`
+  (success actions) and `EQUALS 0` (failure actions).
+- **When.** Any rule too complex for MAP conditions (regex sets, cross-field rules, repeated rows)
+  whose outcome should drive no-code visibility or locking.
+- **Pitfalls.**
+  - **A MAP in the SAME chain as the JS never sees the flag it just wrote** (verified live): input
+    values reach the model after a 500 ms debounce, so the first click always reads the old value
+    and users learn to click twice. Read the flag from a LATER chain, through the trigger field of
+    P2 (FORM-DEV-GUIDE 04 §16), never from the button's own chain.
+  - The field must be *rendered* for JS to find it, so hide it with CSS, not `visible=false` (a
+    hidden element is not in the DOM).
+  - Also re-check silently on later edits and reset the flag to 0, or a user can pass, edit and still
+    confirm.
+  - Make a "Modify" action reset the flag through MAP as well.
+
+## P2. Forward-only step unlocking: one-click Validate + Modify — NEW (supersedes the triad)
+- **Current form (build new steps this way).** One **Validate** button per step. Its chain runs the
+  validator, then asks a global runtime to write the button's branch into a hidden
+  `step-flow-branch` field and increment a hidden `step-flow-trigger` field. That field's own
+  `onInput` chain holds one MAP per step and branch on `flag == 1 AND branch == <its branch>`:
+  lock the step, hide Validate, show **Modify**, reveal the next step. Its last JS block clicks
+  Next. The branch comes from the clicked button, never from a Boolean form variable (P3). **Modify**
+  unlocks the step, resets its flag, hides every later step and resets them to their first-pass
+  state. Measured at about 0.8 s from click to the next step. Recipe, rules and the renderer facts
+  behind it: FORM-DEV-GUIDE 04 §16. Wiring: `procesio form-set-element-chains`.
+- **Legacy form (what production forms were built with).** The triad below needs three clicks per
+  step (validate twice because of the P1 pitfall, then confirm). Migrate it rather than copy it.
+- **Problem.** The native stepper lets users move freely, and a step's data should be final before
+  the next step unlocks.
+- **Mechanics (legacy triad).**
+  - Every step after the first is `visible=false` in the designer.
+  - Each step ends with three buttons: **Validate** (visible), **Modify** and **Confirm** (hidden).
+  - When Validate passes (P1): MAP sets `disabled=true` on every field of the step and shows Modify
+    and Confirm.
+  - Modify: re-enables the fields, resets the flag, hides Confirm.
+  - Confirm: `MAP set <next-step>.visible = true`, then a JS block clicks the stepper's own Next
+    (`.form-builder--stepper--buttons--next button`).
+  - The first step can be unlocked by a process instead (for example a "compute allowed date range"
+    process returns `e_ok` → `<step>.visible`).
+- **When.** Long regulated forms: KYC, contracts, onboarding.
+- **Pitfalls.**
+  - The lock and unlock field lists are hand-maintained in two MAP blocks. Generate or diff them,
+    because copy-paste slips (a field locked twice, another never locked, Modify hiding the wrong
+    button) are the typical bug.
+  - The programmatic Next still passes through any capture-phase Next guard (P6), which is
+    intentional.
+
+## P3. Server-side "render" process drives visibility and options — NEW
+- **Problem.** Which blocks, selects and validate buttons appear depends on a few configuration
+  choices (applicant type × product type × date), and option lists are master data.
+- **Mechanics.** One process takes the configuration selects and returns primitive Booleans
+  (`isA`, `isB`…) plus JSON option lists. The outputMap fans **one Boolean out to many targets**:
+  a form variable (for later conditions), `visible` of each block, and `visible` of that branch's
+  Validate button. Each option list goes to a select's `sourceValue`, and one list can feed several
+  selects.
+- **When.** More than two or three configuration axes, or options that must stay in sync with a DB.
+- **Pitfalls.**
+  - **Never test these Boolean variables with `IS_TRUE` / `IS_FALSE`.** The designer default is the
+    TEXT "False"/"false", and a condition reads any non-empty text as true (measured live). Until
+    the process result lands, every `isX IS_TRUE` passes, so exclusive branches all run. Give the
+    variables a `null` default, or branch with `EQUALS` on the source select. `formlint` flags it.
+  - If later events in the **same** chain read the form variables this process writes, the process
+    must be `syncRun:true`, or they read the previous values (see P13).
+  - Feed downstream processes from the source selects, not from the derived variables.
+
+## P4. Outcome flag pair (`e_ok` / `e_not_ok`) → screen swap — NEW
+- **Problem.** Show a result screen or keep the input screen after an action, without JS.
+- **Mechanics.** Every action process declares two Boolean outputs, `e_ok` (default **false**) and
+  `e_not_ok` (default **true**), and sets them at the end. The outputMap writes `e_ok` → `visible` of
+  the success section and `e_not_ok` → `visible` of the input section or stepper (or of a "retry"
+  button).
+- **When.** Any submit, accept or deny, or sign action.
+- **Pitfalls.**
+  - Keep the defaults pessimistic. A process that stops early then leaves the form on the input
+    screen instead of showing a false success.
+  - Keep one spelling across the workspace (`e_not_ok`, not `e_noOk` / `e_notOk`), or outputMaps
+    silently target nothing.
+  - Never map a Boolean into a file or value slot.
+
+## P5. Cross-step value store read from the Vue model — REFINES 02 §7 / 04 §1
+- **Problem.** The renderer destroys other steps' controls (`v-if`), so client-side validation or a
+  semantic payload spanning steps cannot read their DOM. `ProcesioForm.data.fields` is incomplete
+  for some props (08 "info-text").
+- **Mechanics.** Walk the Vue 3 vnode tree from every element carrying `_vnode`
+  (`vnode.component` → `component.subTree` → `children`, depth-capped). For each component with
+  `props.modelValue`, match it to a field wrapper by DOM containment (`wrap === el ||
+  wrap.contains(el)`). For each id in an explicit `FIELD_IDS` list, store the model value when the
+  field is rendered (even when it is empty, since the model is the truth) and keep the last known
+  value when it is not. Fall back to the DOM value (`checked` for checkboxes). Refresh on a debounced
+  capture listener (`input/change/click/focusout`) and on every `get()`. Expose
+  `get()/json()/values` on `window.parent`.
+- **When.** Multi-step forms whose validation or payload needs values from earlier steps.
+- **Pitfalls.**
+  - `FIELD_IDS` must be the **union** of all steps and **identical** wherever the script is attached.
+    With two copies at the same version and different lists, the first installed wins and later
+    fields are never collected.
+  - Dynamic-table rows repeat ids, so read them separately (P9).
+  - Internals (`_vnode`, `modelValue`) are undocumented. Guard every access.
+
+## P6. Rules-table client validator with step scoping and a Next click-guard — CONFIRMS+ 04 §7 / §15
+- **Mechanics.**
+  - `RULES = { <fieldId>: {required, regex, regexMessage, when(values), optional, date, stripSpaces} }`.
+  - Only fields **currently rendered** are validated, which scopes validation per step for free.
+  - `when` handles conditional branches (for example document type A vs B).
+  - `optional` means "validate the format only if filled". `date:true` means "any parseable date".
+    Date values arrive as ISO, display text or Date objects depending on the read path, so a strict
+    ISO regex gives false negatives.
+  - `stripSpaces` suits bank or ID numbers typed in groups.
+  - Treat arrays, selector option objects (`{label/value}`) and file objects (`{id,name}`) as filled
+    when they have content. A naive `String(value)` check marks them empty.
+  - Errors render under the field, scroll to the first one and clear on edit (only for fields
+    already in error, so the user is not scolded at the first keystroke).
+  - A document **capture** click listener on the stepper's Next blocks navigation on failure and
+    hides any loader.
+  - Also expose semantic payload builders whose keys equal the ones the process-side code expects,
+    so the client and server share one vocabulary.
+- **Pitfalls.**
+  - Port the regexes from the server-side validation and keep them in sync.
+  - See P12 for versioning.
+
+## P7. Global branded loader API bracketing every process chain — REFINES 05 §5
+- **Problem.** Async processes give no feedback, and chains mix JS, process and MAP events.
+- **Mechanics.**
+  - Form-level JS defines `window.parent.__<name>Loader = {show(text,{unsafe,timeout,timeoutMessage}), hide()}`.
+    The overlay and style are injected once by id into the parent document.
+  - Every chain that triggers a process is bracketed: first event `RUN_JAVASCRIPT show('<message>')`,
+    last event `RUN_JAVASCRIPT hide()`, or the navigation block that hides in `finally`.
+  - An optional `unsafe` timeout switches the overlay to a warning state and auto-closes it.
+- **When.** Any form whose processes take over a second.
+- **Pitfalls.**
+  - `hide()` at the end of a chain whose processes are **async** fires before the result arrives,
+    so the loader only covers the launch. Use `syncRun:true` when the loader must cover the work.
+  - Every guard that blocks a click must also call `hide()`, or the veil stays up (08 "loader never
+    lifts").
+  - The element-script `try/catch` around `window.parent.__loader` keeps forms without the loader
+    working.
+
+## P8. Programmatic Next + multi-point scroll reset — REFINES 04 §14
+- **Mechanics.**
+  - Click the stepper's own Next button instead of changing the step index.
+  - Then reset scroll on every candidate (parent window, `top`, `document.scrollingElement`, and any
+    element with `scrollTop>0 && scrollHeight>clientHeight`) at several delays (≈100/400/900 ms)
+    to catch the async re-render.
+  - **Skip** the reset when a validation error element exists, because the validator has already
+    scrolled to the error.
+- **Pitfalls.** The frame hierarchy decides which element scrolls, which is why every candidate is
+  reset.
+
+## P9. Repeated-id rows: pick the visible instance, iterate rows by cell order — CONFIRMS+ 04 §15
+- **Mechanics.** Dynamic-table rows repeat the child's DOM id. Use `querySelectorAll('[id="x"]')`
+  and keep the instance with `offsetParent!==null || offsetWidth>0`. For per-row work, find the
+  enclosing `tr` / `[role=row]` and read the cells in `tableColumnsSourceValue` order. Fall back to
+  row text plus regex when the cell count does not match.
+- **Pitfalls.** Keep row inputs out of the scalar collector and validate them per row instance.
+
+## P10. Whole-form object → declarative SPEC mapper Node — NEW
+- **Problem.** A final submit needs ~150 fields reshaped into a semantic JSON. Mapping each field to
+  a process input is unmaintainable.
+- **Mechanics.**
+  - Map the special source `form` into one JSON process input. It carries `fields.<ElementName>…`
+    plus `instance.*` / `flow.*`.
+  - A reusable subprocess Node holds a SPEC: target keys mapped to source strings like
+    `"Input2.value"` or `"FileUpload1.value.id"`, with annotations after " =" or " (" ignored.
+  - Directives handle the irregular cases: an array from table rows, "first available of A|B",
+    "value of the active sub-select chosen by another select".
+  - A guarded fallback (`SelectN` ↔ `InputN`) is used **only when the source is missing**, and every
+    use is reported in `warnings`.
+  - Dates are normalized. A `SCRIPT_VERSION` marker is emitted in the output so the running version
+    is visible in instance data.
+- **When.** Any large form submit, and any process shared by several variants of the same form.
+- **Pitfalls.**
+  - Field keys are element **names**, so a duplicate name silently collides.
+  - Names can be re-derived in lower case after a designer save (see `PROCESIO-API-NOTES.md`), so
+    resolve case-insensitively.
+  - Files needed as `File` inputs should still be mapped explicitly.
+
+## P11. Process-built HTML into a paragraph label — NEW
+- **Mechanics.** A Node builds a self-contained, **inline-styled** HTML string (counts, percentage
+  bars, inline SVG icons) and returns it as a String output mapped to a paragraph's `label`. Static
+  decoration (separators, section cards, footers) uses the same trick directly in designer labels.
+- **When.** Read-only dashboards, extraction summaries and status cards, with no JS needed.
+- **Pitfalls.**
+  - Only inline styles are reliable, because the page CSS may not target injected markup (08 "A
+    `<div>` written into a paragraph…").
+  - Escape any user or DB text you interpolate, since the label is rendered as HTML.
+
+## P12. Versioned idempotent installers for element-event scripts — REFINES 02 §4–5
+- **Mechanics.**
+  - Each shared script family installs itself on `window.parent.__<family>` with a numeric `v`.
+  - The guard is "install if missing or `v` differs". It runs its action on every execution: install
+    once, act every click.
+  - Iron rule: guard version == exported version, and one file identical everywhere it is attached.
+- **Pitfalls (observed).**
+  - If different buttons carry **different versions**, every step reinstalls. The old document
+    listeners are never removed, so N runtimes then run per click and keystroke.
+  - Header comments drift from the runtime `v`.
+  - A shared style tag guarded by one id keeps the **first** version's CSS.
+  - Prefer the form-level injected-runtime pattern (02 §4), or at minimum keep one canonical file and
+    diff all attachments before publishing.
+  - Listeners created in the sandbox realm are more fragile than an injected `<script>` in the
+    parent.
+
+## P13. Async RUN_PROCESS: outputs do land, but the chain does not wait — REFINES 06 §1 / 08 "outputMap populates nothing"
+- **Observation.** Production forms here map dozens of outputs from `syncRun:false` events (71 async
+  events against 12 sync) and depend on them for visibility and tables. This matches
+  `PROCESIO-API-NOTES.md`: async outputs **arrive later**. It contradicts the guide's "fire and
+  forget, outputMap can never populate" and should be re-verified live.
+- **Rule.** Async is fine when the outputs only paint the UI. Use `syncRun:true` whenever a **later
+  event in the same chain** (MAP condition, JS, another process's inputMap) reads those outputs, or
+  when a loader or Next must wait for them.
+- **Pitfall.** Several async processes on one click (status change + notify + refresh) have no
+  ordering guarantee. Chain them inside one process instead.
+
+## P14. File outputs: `src` to preview, upload `value` to download or carry — NEW
+- **Mechanics.** Map a generated or fetched File output to a file-viewer's `src` (preview) **and** to
+  a file-upload's `value`. The upload then acts as a download link or holds the file so a later
+  event can pass it on as a File input. For uploads, pair the extraction process with a
+  "convert to PDF" process on the same trigger so the preview works for photos too.
+- **Pitfalls.** Keep outputMap targets pointed at existing elements. A deleted viewer leaves a raw
+  path target that fails silently.
+
+## P15. Row object as process input (master/detail) with an explicit reset — NEW
+- **Mechanics.**
+  - A button inside a dynamic row maps `DynamicRowN.$.item` (the whole row object) into a JSON or
+    typed process input.
+  - The detail process returns files and flags. A MAP swaps the list section for the detail section
+    and copies the row into a form variable for later actions.
+  - A "back" button re-loads the list and runs **one MAP that clears every field, viewer and
+    visibility the detail view set**.
+- **Pitfalls.**
+  - Ship only the columns needed. Whole DB rows in a table reach the browser.
+  - Conditions on detail outputs need `syncRun:true` (P13).
+
+## P16. Identity gate via FORM_LOAD → exclusive sections — NEW (with a security caveat)
+- **Mechanics.** FORM_LOAD passes `instance.currentUser.email/name` to a process that returns
+  mutually exclusive Booleans (anonymous / known-but-unregistered / pending / approved), mapped to
+  `visible` of four sections (or of the stepper).
+- **Pitfall (critical).** `visible` is presentation, not authorization. Any data-loading process on
+  the same FORM_LOAD still runs and ships its outputs to the browser. Load protected data only in a
+  process that re-checks the current user itself and returns nothing otherwise.
+  - A condition does not fix that either. `when isConfirmed IS_TRUE` on the data-loading event is
+    evaluated on the variable's default, the TEXT "false", which a condition reads as true (measured
+    live, P3). The load therefore runs for every visitor, and a correct condition would still be only
+    a browser-side check.
+
+## P17. CSS by attribute-id families — NEW
+- **Mechanics.** Style with `[id="…"]` and prefix families (`[id^="separator"]`,
+  `[id^="button-header-"]`) inside `:is()`. Class-level specificity is kept, and decorative elements
+  intentionally share ids so a new one inherits its styling. Hide helper fields on the control and
+  on its wrapper through `:has(> …)` / `:has(> * > …)` so no empty row remains. Every rule is
+  `!important` against the builder's styles.
+- **Pitfalls.**
+  - Duplicate **ids** are fine for decoration only. Keep element **names** unique.
+  - Never reuse a decorative id prefix for a field.
+
+## P18. Process-computed input constraints — NEW
+- **Mechanics.** A load-time or click-time process returns `start_date`, `end_date`, `error` and
+  `e_not_ok`, mapped to a datetime input's `minValue`, `maxValue`, `defaultValue` and `readonly`,
+  and to an error paragraph `label`. Business calendars stay server-side.
+
+## P19. Public token-addressed signing form — NEW
+- **Mechanics.** An email link opens a public form with the token prefilled into an input inside a
+  hidden section. FORM_LOAD verifies the token and returns the documents to viewers plus `e_ok` →
+  section visible. The signature-pad value (a File) plus the token go to a signing process, and a
+  flag pair swaps to a thank-you section.
+- **Pitfalls.**
+  - The token is attacker-controlled. Never interpolate it into SQL: use parameters or validate the
+    format.
+  - Make tokens single-use and expiring.