procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/PROCESIO-INSTANCE-HISTORY-NOTES.md

@@ -0,0 +1,242 @@
+# PROCESIO instance-history API — notes
+
+How run history is read (endpoints + native actions), and the traps. Generalized
+API facts; no client data. Measured live against Internal-PROD, 28/08/2026.
+
+## The endpoints (contract + measured shapes)
+
+- **`GET /api/Projects/{id}/history`** (`get-projects-by-id-history`) — finished,
+  non-archived instances of a process, in a **time window**. Query: `pageNumber`,
+  `pageItemCount` (both required), `filter` (`ProcessTimeSpanFilterType`, default
+  `Last30Days=5`), `monthFilter` (with `CertainMonth=14`).
+- **`GET /api/Projects/{id}/instances`** (`get-projects-by-id-instances`) — **live**
+  runtime instances only. Query: paging + `filterStatus` (repeatable `FlowStatus`).
+  No date filter.
+- **`GET /api/Projects/{id}/instances/count`** — returns `{"result": <int>}`.
+- **`GET /api/Projects/{id}/archive`** — archived (Cassandra) instances, same query
+  as `/history`. Hidden from Swagger; reachable.
+- **`GET /api/Projects/instances/{id}/status`** (`get-instance-status`) — the
+  **primary result reader**. `flowTemplateId` required; `isArchived`/`getActions`/
+  `getVariables`/`getInternalVariables`/`addExtras` default true. Returns
+  `{"instance": {...}}`.
+  Status-poll cost (changed in v3.0.0, 2026-10): `addExtras=true` costs 2-6 extra backend
+  look-ups per call (starter name, webhook, schedule, form names, resource usage). A poll
+  loop that only reads `status` should send all four flags as `false` and fetch the values
+  once at the end (the tool's `run-process` poll does this, then reads `/output`).
+
+**List envelope:** `{result:{totalItemCount, pageNumber, pageItemCount, pageItems[]}}`.
+Read `totalItemCount`, not the row count, to know the true size (page cap hides the rest).
+
+**Paging past the end (changed in v3.0.0, 2026-10).** A `pageNumber` beyond the last page
+no longer returns an empty page: it returns the LAST page again, and `pageNumber` in the
+envelope echoes the page actually served. A paging loop over `/instances`, `/history` or
+`/archive` must stop at `ceil(totalItemCount / <requested page size>)` (use the size you
+sent, not the echoed `pageItemCount`, which shrinks to the total on page 1); waiting for an
+empty page never terminates while rows exist. With `totalItemCount: 0` and `pageNumber > 1`
+the envelope can report `pageNumber: 0`.
+
+## Traps (each cost a real diagnosis)
+
+- ⚠ **`filter` values are calendar buckets, not rolling windows.** `LastYear=13` is the
+  **previous calendar year**, not "last 12 months"; `ThisYear=8` is the current year.
+  A `/history` read with the wrong `filter` returns a well-formed **all-zero envelope
+  indistinguishable from "no history exists."** Runs in the current year need `filter=8`;
+  the endpoint default is `Last30Days=5`. Probe more than one window before concluding empty.
+- ⚠ **`/instances/count` and `/instances` report different tiers.** The count can equal
+  the **history** total while the live `/instances` list is **empty** (finished runs have
+  left the live tier). For finished runs read `/history` (right window), not `/instances`.
+- ⚠ **A history/instance list ROW carries no variables.** camelCase, ~26 fields: identity
+  = `id` (instance id) + `parentId` (the process id) + `title` + trigger (`formName` /
+  `webhookName` / `scheduleName`); timing = `createdOn` / `updatedOn` / `timeConsumed` /
+  `totalTimeConsumed` / `actionsConsumed`; `status` = `FlowStatus` (50 `STATUS_FINISH`,
+  40 `STATUS_RUNNING_WITH_ERRORS`, 6 `STATUS_STOP_BY_USER`). The **outcome is not in the
+  row** — read it per instance from `/status`.
+- ⚠ **`/status` `instance.variables[]` is VariableDto SCHEMA, not runtime values on a
+  historical read.** Each element has `id, name, type` (10 INPUT / 20 PROCESS / 30 OUTPUT /
+  40 SYSTEM / 50 AUTO),
+  `dataType, isList, isError, isRequired, defaultValue` — **no `value` field**.
+  Type 50 AUTO (new in v3.0.0, 2026-10) is engine-written and read-only: the engine creates
+  it on the INSTANCE from action settings meant for it, named `{ActionName}_{PropertyName}`
+  (suffix `_2`, `_3` on a clash, 64-char cap), with the value in `defaultValue`. Today only
+  Call Subprocess uses it (e.g. `Call_Subprocess_ChildInstanceId`, plus a child instance id
+  list). AUTO and SYSTEM variables are always returned on instance / history / archive reads
+  (no `getInternalVariables` needed) and survive data-retention cleanup; PROCESS (20) values
+  are still deleted by it. Clients cannot create or retype either. So a past
+  run's `/status` gives the run record + the variable *definitions*; the concrete output
+  *values* are not on that path (use `isArchived=true` or the `Get Instance Outputs`
+  action). `/output` (`GetInstanceOutput`) is deprecated ("Not used by FE+BE"); prefer
+  `/status`. Casing: **live reads are camelCase; export bundles are PascalCase** — running
+  one shape's keys against the other yields a census of zeros.
+
+## Reading history from INSIDE a flow — binding matters
+
+- ✅ **Native actions read run history with NO credential and NO store binding**
+  (`isProcesioAction=true`, `credential_params=0`):
+  - **`Get Recent Instances`** (`cf514e01-bd19-3b48-8e58-db786c0d7fd2`) — recent instances,
+    status filter ALL/1/6/30/50/40, optional process-id list.
+  - **`Count Recent Instances`** (`d42b8056-4cba-d34d-819c-00295ef66d53`).
+  - **`Get Instance Outputs`** (`98ab31ca-1dd2-fb47-bde7-40171612e4b1`) — a specific
+    instance's OUTPUT variables by name (needs flow + instance id + output selection).
+  - Their process-template-id list is **optional**: *"If this list is null or empty … the
+    entire workspace"* (`docs_info/Procesio Platform Actions.json`). So a flow reads its own
+    workspace's runs/counts/outputs with no foreign binding — the only ids are the pack's own.
+- ⚠ **Call API to the platform's OWN REST API needs a bound REST credential.** `Call API`
+  v1/v2/v3 carry a **required** `credentials` param; only the legacy `Call API`
+  (`cd8bd0bc-9c9c-476c-b16e-975acde804de`) makes it optional — and the history endpoints
+  require a Bearer JWT, so a credential-less legacy call reaches them unauthenticated and
+  fails. A REST credential is a per-workspace, id-bound object that does not travel with an
+  exported pack. **To read run history binding-free, use the native actions, not Call API.**
+
+## Retention — how long a record lives
+
+- **Customer process data: default UNLIMITED**, configurable per Master Workspace and per
+  process (security refs `07-data-protection-gdpr.md`, `13-questionnaire-template.md`). The
+  2-week / 7-day figures are platform **logs** and **backups**, not run data.
+- Per-process **`DataRetentionPolicyDto`** = `{deleteOnSuccess, deleteOnError,
+  deleteOnStopped}`, each `FlowDataRetentionType` (`Never=0`, `AtEndOfRuntime=1`,
+  `AtMoveToHistory=2`). `PATCH /api/Projects/{id}/dataRetention` sets it;
+  `DELETE /api/Projects/instances/{id}/dataRetention` deletes an instance's data.
+  A flow/instance with `DataRetention: null` inherits the workspace default (unlimited).
+- **HIPAA Mode** is opt-in: "Controlled data retention + secure output retrieval"
+  (`08-application-security.md`) — can delete/secure outputs when enabled.
+- Tiers: live `/instances` → `/history` (non-archived, windowed) → `/archive` (Cassandra,
+  `isArchived=true`). Tier moves are storage progression, **not deletion by default**.
+- **Consequence for a run-history feature:** history is durable by default, so it can back a
+  log — but a customer's per-workspace/per-process retention policy or HIPAA Mode can delete
+  it, and a silently-aged-out history turns "did we process this?" into a confident wrong "no".
+
+### Process-History v3.0.0 fixes (2026-10, shipped without an announcement)
+
+- A failed history insert no longer deletes the runtime row. Before, such an instance vanished
+  from BOTH `/instances` and `/history`; an instance missing from both on an older run may be
+  this defect, not retention.
+- A retry of the move no longer overwrites the archived variables with an empty list.
+- Instances move from `/instances` to `/history` faster, so the window in which a fresh run is
+  visible only in `/instances` is shorter. Still read both tiers before calling a run unlisted.
+
+## `Get Recent Instances` at RUNTIME — measured, and it corrects the action doc
+
+Executed live (E-166); two documented behaviours did **not** reproduce, so verify before you
+rely on them:
+
+- **It is a RECENT-WINDOW read.** A process's older *finished* runs read as `griTotal 0`
+  until a fresh run appears, then the fresh one shows. A run-history view MUST set the window
+  deliberately (default `Last30Days`); trusting the default to reach back far enough returns
+  a well-formed zero for runs that really happened (the census-of-zeros, on the native action
+  now, not only the `/history` calendar bucket).
+- **A single process id filters correctly** in EITHER `Select Process` or `Process Template
+  Id`. The Result rows carry `{Id, Status, UpdatedOn}` **only — no `parentId`/title**, so you
+  cannot tell processes apart per-row; the *filter value* is the only scoping.
+- ⚠ **A LIST value in the process filter FAULTS at runtime.** A two-element id list
+  (`[pidA, pidB]`) in either param validates and `put-projects` fine, but the run returns
+  `griTotal = null` / 0 rows (a fault, not "0 matches") — tested with both processes freshly
+  run, so not a window effect. The friendly builder DSL additionally rejects a list literal at
+  the config-schema layer and a variable binding at back-end validation.
+- ⚠ **An omitted / null filter returns 0 — NOT the whole workspace.** The action doc's "if
+  this list is null or empty … the entire workspace" did not reproduce for an omitted filter.
+- **Therefore: to show N processes' histories, do N single-id reads and union them** — not one
+  list value, not the null=whole-workspace shortcut. (Bounded residual: the designer's own
+  multi-select picker may store a Value shape the action accepts that a bare id-list does not;
+  untested.) Reading a past run's OUTPUT *values* back works — via `/status` `defaultValue`
+  and `/output` `result.variable[<name>]`, not gated by `isArchived` (E-164 F-1310).
+
+## Capturing a run's output — capture it LIVE, don't count on reading it back
+
+- ⚠ **`run-process` (POST /api/Projects/{id}/run) is fire-and-forget: it returns only
+  `{instanceId}` and launches asynchronously.** To get the run's output in one call pass
+  **`--synchronous`** (`run-process --id … --synchronous --timeout N`) — it polls to a terminal
+  status and returns `{instanceId, status, variable{<name>: <value>}, error}`. Without it you get
+  the id and nothing else. `run-process-with-file` already publishes → uploads → launches →
+  **polls** → returns that same output shape, so it needs no flag.
+- ⚠ **A finished instance's output can be UNREADABLE afterwards, so capture at run time.**
+  Measured 01/09/2026 on finished scratch instances (status 50, minutes old): `/status`
+  (`get-instance-status`) returned **HTTP 400 / statusCode 450 "Database requested information not
+  found"** *even with `flowTemplateId` supplied*, and `/output` (`get-instance-output`) returned
+  **HTTP 500 wrapping 403** (it is the deprecated path). This does **not** contradict E-164's
+  "past-run values readable via `/status` `defaultValue`" as a rule — that was measured on a
+  deployed card, likely inside its retention/live window — but it shows the read-back is **not
+  guaranteed** for an arbitrary finished instance (retention policy, elapsed window, or workspace
+  tier can take it away). **The reliable pattern: capture the output synchronously as the run
+  finishes** (`--synchronous` / `run-process-with-file`); treat a later `/status` read-back as a
+  best-effort bonus, not the capture path. The list-instances row (identity + `status` + timing) is
+  always there to prove a run landed; the run's *values* are not.
+
+## Only FORM-launched instances are LISTED; API-launched ones are only COUNTED
+
+> ⚠⚠ **CONTRADICTED 2026-09-16 — re-measure before relying on this section.** Runs launched
+> through `POST /api/Projects/{id}/run` (synchronous and asynchronous) and through an anonymous
+> webhook launch WERE listed: they appeared in `…/instances` first and then in `…/history`
+> within minutes, in three workspaces, with and without recording enabled. The rows move
+> between tiers on a timer, so a list read a few minutes after a run can show nothing in
+> `/instances` while `/history` holds the run. The most likely explanation of the reading
+> below is that tier move, not a route-dependent listing rule; that explanation is inferred,
+> not measured. Always read `/instances` AND `/history` before concluding a run is unlisted.
+
+Verified live on one flow, both ways, same day:
+
+| launch route | `…/instances/count` | `…/instances` (list) | `Get Recent Instances` |
+|---|---|---|---|
+| process API (`/api/Projects/{id}/run`, publish→launch) | 41 | `totalItemCount: 0`, `pageItems: []` | `[]` |
+| form API (`/api/FormProcess/…` — what a browser does) | +1 | the run, with `formName` populated | the run |
+
+The listed row carries `formName`, `actionsConsumed`, `timeConsumed` and the submitter's
+name — fields an API launch has no value for. That is the tell: the history list is a record
+of **form submissions**, not of flow executions.
+
+**Consequences.**
+
+- A run-history view tested only through the process API reads as permanently empty, and the
+  natural conclusion — "the history flow is broken" — is wrong. Nothing is broken; the query
+  is correct and the store genuinely holds no listable rows yet.
+- `Get Recent Instances` returning `[]` while `Count Recent Instances` returns a positive
+  number is not a contradiction and not a bug. Count and list are answering different
+  questions.
+- **Acceptance for any card shipping a run-history view must include one submission through
+  `run-form-with-files`.** Without it the view cannot be distinguished from a broken one, and
+  a mockup render will fill the gap in review — which is exactly how a fabricated "-LIVE"
+  view gets shipped.
+
+Generalises: where a platform exposes both a machine route and a UI route to the same
+action, the audit trail may only record the UI route. Test the route the user will take.
+
+## The three response shapes, measured field-by-field (10/09/2026)
+
+Measured against a scratch workspace on Internal-PROD. Field NAMES only; no values recorded.
+These are the shapes anything that pre-fills a diagnostic bundle from the product has to bind to.
+
+**Envelope:** `GET /api/Projects/instances/{id}/status` returns `{"result": {"instance": {…}}}`.
+
+**`instance` — 33 fields:** `actions, actionsConsumed, active, canvasData, createdBy, createdById,
+createdOn, currentActionId, customResponse, dataRetention, debugMode, description, firstName, formName,
+id, isNotification, isValid, lastName, parentFlow, parentId, scheduleName, status, timeConsumed,
+timeout, title, updatedBy, updatedById, updatedOn, variables, webhookName, webhooks, workspaceId,
+workspaceName`.
+
+**`instance.actions[]` — 19 fields:** `actionName, actionTemplateName, breakPoint, category, customData,
+errorMessage, events, flowId, id, isDisabled, isTestable, parameters, parentId, ports, status,
+templateId, testValues, variableErrorId`.
+→ **The error lives on the ACTION, not on the instance.** Select failed actions as those whose
+`errorMessage` is non-empty; `variableErrorId` names the error-port variable. `currentActionId` on the
+instance points at the action in flight.
+
+**`instance.variables[]` — 9 fields:** `contextId, dataType, defaultValue, id, isError, isList,
+isRequired, name, type`. **No `value` field**, confirming that a historical read yields the variable
+SCHEMA and not runtime values. Values need the `Get Instance Outputs` native action or a synchronous run.
+`type` takes 10 INPUT / 20 PROCESS / 30 OUTPUT / 40 SYSTEM / 50 AUTO (50 added in v3.0.0, 2026-10:
+engine-written, value in `defaultValue`, always returned, survives retention cleanup; see the
+Traps section above). **Measured live in prod:** on 2026-10-21 the engine already created these variables with the new readable names (`Call_Subprocess_InstanceId`, `Call_Subprocess_ChildInstanceId` holding the child's id, `Call_Subprocess_ChildInstanceIdList`) but typed them 20 (PROCESS), because the Call Subprocess template still served those settings as `ignore`. From 2026-10-22 the template serves `auto` and new runs type `Call_Subprocess_ChildInstanceId` and `Call_Subprocess_ChildInstanceIdList` as **50 (AUTO)**, holding the child's id; `Call_Subprocess_InstanceId` stays 20 because its setting is still `ignore`. Instances started before the fix keep type 20, so a reader that must cover older history should match by NAME, not by `type == 50`. Survival through data-retention cleanup is not verified yet.
+
+**`/history` row — 26 fields:** as listed earlier in this note, plus confirmed presence of
+**`currentActionId` and `workspaceId` on the row itself**, so a sweep can shortlist candidates without a
+per-instance `/status` call. The outcome is still not on the row.
+
+### ⚠ There is no version anywhere on either object
+
+`instance` has no version-shaped key, and `GET /api/Projects/{id}` returns `{result:{flow:{…}}}` whose 27
+keys contain none either. `updatedOn` / `updatedBy` / `updatedById` record **that** a flow was edited and
+**by whom**, never **what** changed: no endpoint returns a diff, a revision or a change log.
+
+Generalises: **a record that carries an "updated" timestamp and an author is not a version history, and
+treating it as one turns "what changed?" into an unanswerable question at exactly the moment it is
+asked.** Any workflow whose next step depends on the previous definition must capture that definition
+itself at the time it runs, because the platform will not reconstruct it afterwards.

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

@@ -0,0 +1,201 @@
+# PROCESIO metering — where run cost actually lives, and where it does not
+
+How to read what a process run consumed. Written after an attempt to measure the
+cost of a long-running run found the obvious endpoint empty and a better one
+undocumented. Auth/connection mechanics stay in
+[PROCESIO-AUTH-NOTES.md](PROCESIO-AUTH-NOTES.md).
+
+> ## ⚠ CORRECTION, 31/08/2026 — READ THIS BEFORE §2
+>
+> **§2 below was wrong about what the per-instance figures mean, and the error
+> was the expensive kind: it named a live-looking instrument as the fallback for
+> a dead one.** Controlled measurement on an unmetered workspace, with a positive
+> control on every reading:
+>
+> | what was done | what the platform recorded |
+> |---|---|
+> | 100,001 ms of busy loop inside Node actions, 5 runs | **31 ms** total |
+> | a Call API blocked for 30,000 ms by the callee | **14 ms** |
+> | a Call API blocked for 120,000 ms | **8 ms** |
+> | a Call API blocked for 300,000 ms | **15 ms** |
+>
+> `timeConsumed` is **not** wall-clock occupancy and does **not** include time
+> spent waiting on a reply. It is flat in the single-to-low-double-digit
+> milliseconds whatever the action does, and `timeConsumed == totalTimeConsumed`
+> in every reading — including a five-minute wait, where §2 predicts the widest
+> divergence. Treat both fields as **per-action orchestration overhead**, not as
+> a measure of work.
+>
+> **The rule this leaves.** On a workspace with `subscriptionType: null` there is
+> no endpoint that prices a run: the quota counter is dead (§1), the per-instance
+> figures are blind to compute and to waiting, and the per-process endpoints
+> return empty. If a decision needs the cost of a long wait, it cannot be
+> measured on an unmetered account — say so and name it as a blocker, rather than
+> substituting a number from an instrument that has not been shown to track the
+> work. **Prove the instrument moves with the work before believing any figure it
+> reports** — the same rule §1 states for the quota counter applies to its
+> replacement, and skipping that step is exactly how the fallback was adopted.
+>
+> The instance-level fields remain useful for what they DO report reliably:
+> `actionsConsumed` (an action count) and the existence and status of an instance.
+
+---
+
+## 1. `/api/Resources/used` is the QUOTA, and it may carry no consumption at all
+
+`GET /api/Resources/used` returns the workspace's time budget:
+
+```json
+{"result": {"subscriptionType": null, "price": 0.0,
+  "time": {"consumed": 0, "masterConsumed": 0, "canExceedPaidTime": true,
+           "limit": {"soft": 36000000, "hard": 36000000},
+           "notifyThreshold": 28800000},
+  "average": {"platform": {"total": 0, "internal": 0, "external": 0}, "custom": 0},
+  "expirationDate": "...", "autoRenewable": true}}
+```
+
+**The budget is published even when nothing is counted against it.** On a workspace
+with **`subscriptionType: null`** every consumption field stays at `0` — before a
+run, after it, and after many runs across an hour. It is not a settling lag and it
+is not a disabled recorder: `GET /api/ResourceTrackingConfig` reports
+**`isRecordingEnabled: true`** on the same workspace.
+
+**The trap:** the endpoint answers `200` with a plausible-looking body, so a
+before/after diff reads as "this run cost nothing" rather than "this endpoint does
+not measure". **Never infer cost from a zero delta here.** Prove the counter moves
+at all before interpreting any reading from it; if `subscriptionType` is null,
+expect it not to.
+
+Scope note: these endpoints are workspace-scoped. `MasterWorkspace.Read` variants
+(`/api/Resources/used/subworkspaces`, `/api/Subscriptions`, the
+`executionEnvironment/concurrency` analytics) return **403** to a sub-workspace
+credential.
+
+## 2. The real per-run meter is per INSTANCE, and it is in two places
+
+Both are populated immediately and on any workspace, metered or not.
+
+**`GET /api/Projects/{processId}/instances`** — each `pageItems[]` entry carries:
+
+| Field | Meaning |
+|---|---|
+| `actionsConsumed` | actions executed in that instance |
+| `timeConsumed` | **wall-clock occupancy**, including time spent waiting on a reply |
+| `totalTimeConsumed` | **compute**, the time actions spent executing |
+| `timeout` | the instance's own timeout setting |
+
+**`GET /api/Resources/analytics/instances/{instanceId}/details`** — the same run
+broken down by action type:
+
+```json
+{"result": [{"instanceId": "...", "actionName": "Node",
+             "totalRuns": 15, "totalTime": 200, "actionExecutionTime": 198}]}
+```
+
+`totalTime` ↔ `timeConsumed`; `actionExecutionTime` ↔ `totalTimeConsumed`.
+
+### The naming is inverted from intuition — check it, do not trust it
+
+**`totalTimeConsumed` is the SMALLER figure.** It is compute. `timeConsumed`, which
+sounds like the subset, is the larger occupancy figure. Verify the pairing on a
+known instance before building anything on it: read both endpoints for the same
+instance id and confirm which number is larger.
+
+### The two columns diverge exactly where a wait is
+
+Occupancy minus compute is the time an action spent blocked. On a flow whose actions
+are all local the two are nearly equal; on a Call API waiting for a reply they
+separate sharply (observed: an action at `totalTime` 747 ms against
+`actionExecutionTime` 5 ms). Across repeated runs **compute is stable and occupancy
+is volatile**, and all the volatility sits in the calls that wait.
+
+## 3. The two endpoints can permanently DISAGREE about the same instance
+
+Observed on the run with the longest wait in a set: the details endpoint reported
+fewer actions and a lower total than the instance list, and **the two never
+converged** across re-reads minutes and then tens of minutes apart.
+
+Worse for anyone testing for lag: **the details endpoint was stable across two reads
+thirty seconds apart while still being incomplete.** Two matching reads are not proof
+of settlement. Reconcile the two endpoints against each other rather than trusting a
+repeat read of one.
+
+## 4. Nested processes are metered SEPARATELY, and occupancy double-counts them
+
+A process reaching another through **Call API** launches a **separate instance** with
+its own `actionsConsumed` / `timeConsumed` / `totalTimeConsumed`. While the caller's
+Call API waits, the callee is executing and billing its own instance.
+
+Consequences:
+
+- **Count the whole call tree, not the entry instance.** An entry process's action
+  count can be a fraction of the request's true total once its callees are added.
+  Comparing an entry instance's count against a whole-tree figure loses the
+  difference silently.
+- **On the occupancy column the same stretch of time appears twice** — as the
+  caller's wait and as the callee's run. On the compute column it appears once.
+
+## 5. What the vendor documents about which time is charged
+
+From the PROCESIO docs (processing-time FAQ). **Documented, not verified by
+measurement** — the endpoint that would confirm it is the one in §1:
+
+- *"the processing time is consumed while waiting for an external service to reply
+  as a running process consumes resources on our infrastructure"* — **a blocking
+  external call is charged for the whole wait.**
+- *"Delay action is counted only while during its processing. But for the period set
+  to delay... the action is not processing, and therefore this delay time is not
+  counted"* — **a parked Delay is exempt.**
+- *"webhooks that trigger a process are not counted against the processing time"*.
+- The stated platform average is **~100 ms per action**.
+
+**The measurement trap this creates:** a Delay is the natural way to synthesise a
+long run, and it is the one mechanism documented as exempt. Timing a Delay therefore
+measures the exempt case and says nothing about a blocking call. **To measure what a
+long external wait costs, the long run must be produced by a call that blocks**, not
+by a Delay.
+
+## 6. Timeouts
+
+| Timeout | Value | Applies to |
+|---|---|---|
+| **Instance / process** | **none.** Per-instance `timeout: 0`; docs state a per-process timeout "is not possible" and the feature does not exist | nothing kills a long run |
+| **Call API action** | min **60 s**, max **3600 s** | one HTTP call |
+| **AI Decisional action** | 1–3600 s, default 60 s | one provider call |
+| **Node action** | integer; throws on expiry | one script |
+| **Synchronous launch** | `?runSynchronous=true&secondsTimeOut=N` (300 in the documented example, **no maximum stated**) | the caller's own wait |
+
+A run is not bounded by the platform. It is bounded by whichever action timeout it
+trips first.
+
+## 7. Instance history is trimmed aggressively, and the two endpoints differ
+
+Only a handful of instances per process survive. **Do not plan to read an
+interesting run later** — capture its figures in the same script that launches
+them.
+
+Trimming is faster than "within days": rows have been observed ageing out of
+`GET /api/Projects/{id}/instances` **within about eight minutes**, one by one,
+with no new runs to displace them. The analytics **details endpoint outlived the
+list** for the same instance, so the two have different retention and a missing
+row in one is not proof the run is gone from the other.
+
+## 9. Resource recording defaults to OFF on a new workspace
+
+`GET /api/ResourceTrackingConfig` reports `isRecordingEnabled` per workspace, and
+a freshly created workspace can arrive with it **false** and a zeroed `gid`. In
+that state the analytics details endpoint returns an **empty array** while the
+instance list still answers — so a zero from the details endpoint is confounded
+between "not recorded" and "not consumed" until the flag is read.
+
+Check the flag before interpreting any analytics zero.
+`PUT /api/ResourceTrackingConfig/toggle/{true|false}` sets it (needs
+`Workspace.Admin`) and creates the per-workspace record. Note that enabling it
+does **not** make the figures track the work — see the correction at the top of
+this file; it only makes the details endpoint answer at all.
+
+## 8. Wall-clock measured by a polling harness is not the run
+
+A harness that polls on an interval quantises to that interval: runs the platform
+records at a few hundred milliseconds read as ~9 s against a 5 s poll. **Use the
+platform's own figures for duration**, never the harness's elapsed time.