docs(workflow-builder): walk Parts 2 and 14; fix the 14.1 example

Parts 2 and 14 had never been walked in a browser. Part 14 is where the
/dynamic-nodes admin breakage lived, so it went first.

19 of 19 runnable checks now walked. Three pass outright and needed nothing;
the rest surfaced five findings, one already fixed in 64d86d7:

  D-9  the plan's OWN 14.1 example cannot publish — `dynamicNode(ctx, params)`
       is untyped and `deno check` runs under noImplicitAny, so the first
       command in Part 14 400s and everything downstream cascades. Replaced
       with a typed script matching the editor boilerplate. (fixed here)
  D-10 publishing from the palette modal never dropped the node (fixed,
       64d86d7)
  D-11 Try/Run stay enabled on a graph whose dyn lineage is deleted, which the
       validator already reports as an error. NEEDS A RULING: does any error
       disable Try, or only structurally-unrunnable ones?
  D-12 a succeeded non-deterministic dyn node previews "cache evicted, re-run
       to repopulate" — nothing was evicted and re-running can never
       repopulate it, because such nodes are deliberately never cached
  D-13 the script editor fetches Monaco from cdn.jsdelivr.net at runtime. TLS
       interception (what a government network does) leaves it on "Loading…"
       forever with no error and Publish still enabled. monaco-editor is
       already in node_modules at the exact version served

Security tier is genuinely solid: net egress, remote import and env access are
all denied by the Deno sandbox, allowlisting a host lifts the denial (proving
the allowlist is the gate), and the full typed-error matrix is 14/14 green
against the live runner.

Also records a method note — my first reading of D-11 was wrong because I
sampled while the activity catalog was still loading, and dyn.* types are
deliberately given the benefit of the doubt until it resolves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: alex-struk

docs-md/workflows/MANUAL_TEST_PLAN.md

@@ -173,11 +173,11 @@ Each test below is one of: **✅ E2E** (a Playwright spec guards it), **🔬 uni
 
 ## Part 2 — Smoke Test (bring-up verification)
 
-- [ ] **2.1** `curl -H "x-api-key: <KEY>" http://localhost:3002/api/workflows` returns `200` with a JSON array.
-- [ ] **2.2** `curl http://localhost:9099/health` returns `{"ok":true,"denoVersion":"2.1.4"}`. ⚙️
+- [x] **2.1** `curl -H "x-api-key: <KEY>" http://localhost:3002/api/workflows` returns `200` with a JSON array.
+- [x] **2.2** `curl http://localhost:9099/health` returns `{"ok":true,"denoVersion":"2.1.4"}`. ⚙️
 - [ ] **2.3** Browse to http://localhost:3000, complete IDIR login, land on the app shell. 🔑
-- [ ] **2.4** Temporal UI at http://localhost:8088 loads and shows the `default` namespace.
-- [ ] **2.5** Navigate to `/workflows` → list page renders with the kind filter (`Workflows / Libraries / All`).
+- [x] **2.4** Temporal UI at http://localhost:8088 loads and shows the `default` namespace.
+- [x] **2.5** Navigate to `/workflows` → list page renders with the kind filter (`Workflows / Libraries / All`).
 
 ---
 
@@ -583,36 +583,40 @@ One `source.api` and one `source.upload` max per workflow.
 `DYNAMIC_NODE_ALLOW_NET` must be set **identically on both the backend and the Temporal worker** (read at startup — restart both to change). Unset = only the API base host is auto-granted.
 
 ### Publish / manage (API)
-- [ ] **14.1 Publish (create).**
+- [x] **14.1 Publish (create).**
   ```bash
+  # NOTE: `deno check` runs under `noImplicitAny` — an untyped
+  # `dynamicNode(ctx, params)` fails with `400 stage:"ts-check"` before the
+  # lineage is ever created. Type the parameters, as the editor boilerplate and
+  # `seed-feature-demos.mjs` both do.
   curl -X POST http://localhost:3002/api/dynamic-nodes -H "x-api-key: <KEY>" \
     -H "content-type: application/json" \
-    -d '{"script":"/**\n * @workflow-node\n * @name uppercase-url\n * @description Uppercases the document URL.\n * @inputs { document: { kind: \"Document\", required: true } }\n * @outputs { uppercased: { kind: \"Artifact\" } }\n */\nexport default async function dynamicNode(ctx, params){ return { uppercased: { url: ctx.document.url.toUpperCase() } }; }"}'
+    -d '{"script":"import type { Document } from \"@ai-di/graph-workflow/kinds\";\n\n/**\n * @workflow-node\n * @name uppercase-url\n * @description Uppercases the document URL.\n * @inputs { document: { kind: \"Document\", required: true } }\n * @outputs { uppercased: { kind: \"Artifact\" } }\n */\nexport default async function dynamicNode(\n  ctx: { document: Document },\n  _params: Record<string, unknown>,\n): Promise<{ uppercased: { url: string } }> {\n  const url = String((ctx.document as { url?: string }).url ?? \"\");\n  return { uppercased: { url: url.toUpperCase() } };\n}"}'
   ```
   **Pass:** `201 {slug:"uppercase-url", version:1, signature:{…}, errors:[]}`.
-- [ ] **14.2 Publish negative cases.** Malformed JSDoc → `400 stage:"jsdoc-parse"`; unknown kind → `400 stage:"signature-semantics"`; TS type error → `400 stage:"ts-check"` (from runner); duplicate of a **live** slug → `409 DUPLICATE_SLUG` (a *soft-deleted* slug re-POST **restores** instead — see 14.14).
-- [ ] **14.3 New version (update).** `PUT /api/dynamic-nodes/uppercase-url` with a modified script. **Pass:** `200 {version:2}`. `@name` ≠ path → `409 NAME_MISMATCH`; unknown/soft-deleted → `404`.
-- [ ] **14.4 List / detail.** `GET /api/dynamic-nodes` (+ `/:slug`). **Pass:** list sorted by slug, excludes soft-deleted, includes `headVersion`, `versionCount`, `usedInWorkflowCount`.
-- [ ] **14.5 Soft-delete.** `DELETE /api/dynamic-nodes/uppercase-url`. **Pass:** `200 {slug, deletedAt}`, idempotent, returns used-in-N count.
-- [ ] **14.6 Merged catalog.** `GET /api/activity-catalog`. **Pass:** includes `dyn.uppercase-url` with `dynamicNodeSlug/Version` + `colorHint:"dyn"` after static entries. A different group’s key does **not** see it (30s cache — allow a moment).
-- [ ] **14.14 Restore-on-republish.** Publish `uppercase-url` (v1) → **14.5 soft-delete** it → `POST /api/dynamic-nodes` with the **same** `@name`. **Pass:** `201` and the lineage is **restored** — `version` continues the history (`v2`, not a fresh v1), `GET /:slug` is live again (`deletedAt:null`) with both versions. Re-POST once more while live → `409 DUPLICATE_SLUG` (the guard still fires for a genuine live clash). In the UI: delete a custom node, then **New custom node** with the same name — it re-appears instead of dead-ending. (`@infra` e2e: `tier1-dynamic-node`.)
+- [x] **14.2 Publish negative cases.** Malformed JSDoc → `400 stage:"jsdoc-parse"`; unknown kind → `400 stage:"signature-semantics"`; TS type error → `400 stage:"ts-check"` (from runner); duplicate of a **live** slug → `409 DUPLICATE_SLUG` (a *soft-deleted* slug re-POST **restores** instead — see 14.14).
+- [x] **14.3 New version (update).** `PUT /api/dynamic-nodes/uppercase-url` with a modified script. **Pass:** `200 {version:2}`. `@name` ≠ path → `409 NAME_MISMATCH`; unknown/soft-deleted → `404`.
+- [x] **14.4 List / detail.** `GET /api/dynamic-nodes` (+ `/:slug`). **Pass:** list sorted by slug, excludes soft-deleted, includes `headVersion`, `versionCount`, `usedInWorkflowCount`.
+- [x] **14.5 Soft-delete.** `DELETE /api/dynamic-nodes/uppercase-url`. **Pass:** `200 {slug, deletedAt}`, idempotent, returns used-in-N count.
+- [x] **14.6 Merged catalog.** `GET /api/activity-catalog`. **Pass:** includes `dyn.uppercase-url` with `dynamicNodeSlug/Version` + `colorHint:"dyn"` after static entries. A different group’s key does **not** see it (30s cache — allow a moment).
+- [x] **14.14 Restore-on-republish.** Publish `uppercase-url` (v1) → **14.5 soft-delete** it → `POST /api/dynamic-nodes` with the **same** `@name`. **Pass:** `201` and the lineage is **restored** — `version` continues the history (`v2`, not a fresh v1), `GET /:slug` is live again (`deletedAt:null`) with both versions. Re-POST once more while live → `409 DUPLICATE_SLUG` (the guard still fires for a genuine live clash). In the UI: delete a custom node, then **New custom node** with the same name — it re-appears instead of dead-ending. (`@infra` e2e: `tier1-dynamic-node`.)
 
 ### Editor UI
-- [ ] **14.7 Management page.** Left-nav **Dynamic nodes** → `/dynamic-nodes` list → **New dynamic node** → editor with prefilled boilerplate → edit → watch the **live parse strip** (300ms debounce) show green “Signature OK” or red line-anchored errors → Publish. **Pass:** on success the palette/catalog refresh **without a Vite restart**; on `400`, errors also show as Monaco gutter squiggles and clicking jumps to the line.
+- [x] **14.7 Management page.** Left-nav **Dynamic nodes** → `/dynamic-nodes` list → **New dynamic node** → editor with prefilled boilerplate → edit → watch the **live parse strip** (300ms debounce) show green “Signature OK” or red line-anchored errors → Publish. **Pass:** on success the palette/catalog refresh **without a Vite restart**; on `400`, errors also show as Monaco gutter squiggles and clicking jumps to the line.
 - [ ] **14.8 In-canvas custom node.** Palette **Custom** section → **New custom node** modal → publish → node auto-drops as `dyn.<slug>` with a grape **DYN** badge. Right-click a `dyn.*` node → **Edit script**. **Pass:** deleted-lineage node shows a red **Deleted** badge, settings Alert, Try disabled.
 
 ### Execute + security
 - [ ] **14.9 Execute (Try).** Build `source.api → dyn.uppercase-url`, wire `document`, Save → **Try** with `{"documentUrl":"https://example.com/foo.pdf"}`. **Pass:** node goes blue→green; preview shows the uppercased URL. Publish v2 (reverse) → Try → cache miss → preview shows reversed URL.
-- [ ] **14.10 Runtime errors.** Script `throw` → `errorMessage` prefixed `[DynamicNodeRuntimeError] exitCode=1 …`; timeout (>60s) / stdout >5MB / invalid JSON / missing output port each map to their typed error (truncated 2KB).
-- [ ] **14.11 🔒 Network egress blocked.** Publish/run a node doing `await fetch("https://blocked.example.com")` with that host **not** in `DYNAMIC_NODE_ALLOW_NET`. Fast path — hit the runner directly:
+- [x] **14.10 Runtime errors.** Script `throw` → `errorMessage` prefixed `[DynamicNodeRuntimeError] exitCode=1 …`; timeout (>60s) / stdout >5MB / invalid JSON / missing output port each map to their typed error (truncated 2KB).
+- [x] **14.11 🔒 Network egress blocked.** Publish/run a node doing `await fetch("https://blocked.example.com")` with that host **not** in `DYNAMIC_NODE_ALLOW_NET`. Fast path — hit the runner directly:
   ```bash
   curl -X POST http://localhost:9099/execute -H "content-type: application/json" -d '{
     "script":"export default async function(){ await fetch(\"https://blocked.example.com\"); return {ok:true}; }",
     "inputCtx":{},"parameters":{},"allowNet":[],"ambientEnv":{},"timeoutMs":5000,"maxMemoryMB":128}'
   ```
   **Pass:** `exitCode != 0`, stderr mentions Deno net permission denied. Add the host to `allowNet` → same script succeeds (proves the allowlist is the gate). ⚠️ Locally the container still has NAT internet — you’re verifying the per-script Deno permission gate, not container isolation (true isolation only in OpenShift).
-- [ ] **14.12 🔒 Remote import blocked.** Script with `import … from "https://blocked.example.com/mod.ts"` where the host isn’t allowlisted. **Pass:** either `400 stage:"allowlist"` at publish (rejected host listed) or a runtime net-permission failure — never an actual outbound fetch.
-- [ ] **14.13 🔒 Env isolation.** A script reading `Deno.env.get("PATH")` (or anything beyond the 4 ambient vars `AI_DI_API_BASE_URL/API_KEY/GROUP_ID/WORKFLOW_RUN_ID`) returns undefined/fails. **Pass:** no host env leaks into the subprocess.
+- [x] **14.12 🔒 Remote import blocked.** Script with `import … from "https://blocked.example.com/mod.ts"` where the host isn’t allowlisted. **Pass:** either `400 stage:"allowlist"` at publish (rejected host listed) or a runtime net-permission failure — never an actual outbound fetch.
+- [x] **14.13 🔒 Env isolation.** A script reading `Deno.env.get("PATH")` (or anything beyond the 4 ambient vars `AI_DI_API_BASE_URL/API_KEY/GROUP_ID/WORKFLOW_RUN_ID`) returns undefined/fails. **Pass:** no host env leaks into the subprocess.
 
 ---
 

feature-docs/20260724-workflow-builder-spec-completion/WALKTHROUGH_PARTS_2_14.md

@@ -0,0 +1,148 @@
+# Walkthrough — Parts 2 and 14 (2026-07-27)
+
+Continuation of `WALKTHROUGH_PARTS_3_9.md`, which covered Parts 3–9 only. Parts
+2, 4, 10–16 had **never been walked in a browser**. This pass takes Part 2
+(smoke) and Part 14 (dynamic nodes) — the part that produced the
+`/dynamic-nodes` admin breakage Alex hit on 2026-07-27.
+
+## Environment
+
+Full local stack: backend + Temporal server + **Temporal worker** + postgres +
+minio + deno-runner (`{"ok":true,"denoVersion":"2.1.4"}`). Everything in Parts 2
+and 14 was runnable.
+
+## Part 2 — Smoke
+
+| # | Verdict | Evidence |
+|---|---|---|
+| 2.1 API reachable | ✅ PASS | `200`, 25 workflows. *Plan nit: it returns `{workflows:[…]}`, not a bare JSON array.* |
+| 2.2 deno-runner health | ✅ PASS | `{"ok":true,"denoVersion":"2.1.4"}` verbatim |
+| 2.3 IDIR login | ⏭ NOT AUTOMATABLE | needs real IDIR credentials; the mock-auth bypass reaches the app shell, which is as close as automation gets |
+| 2.4 Temporal UI | ✅ PASS | `200`; namespaces `["temporal-system","default"]` |
+| 2.5 Workflows list + kind filter | ✅ PASS | 25 rows; segmented control reads `Workflows / Libraries / All` |
+
+## Part 14 — Dynamic (custom-code) nodes
+
+| # | Verdict | Evidence |
+|---|---|---|
+| 14.1 Publish (create) | ⚠️ **PASS only after fixing the plan** | see D-9 |
+| 14.2 Publish negatives | ✅ PASS | `jsdoc-parse` "Missing @workflow-node marker"; `signature-semantics` "Unknown kind: NotAKind"; `ts-check` line 15; `409 DUPLICATE_SLUG` |
+| 14.3 New version | ✅ PASS | `200 {version:2}`; `@name` mismatch → `409 NAME_MISMATCH`; unknown slug → `404` |
+| 14.4 List / detail | ✅ PASS | slug-sorted; `versionCount:2`, `head:2`; detail newest-first `[2,1]` |
+| 14.5 Soft-delete | ✅ PASS | `200`, byte-identical `deletedAt` on the second call (idempotent), excluded from list |
+| 14.6 Merged catalog | ✅ PASS (one half) | both `dyn.*` entries carry `dynamicNodeSlug/Version` + `colorHint:"dyn"` and sit after all 41 static entries. **Cross-group isolation not provable with one API key** — the negative is: a non-admin naming a foreign group is refused outright |
+| 14.7 Management page | ✅ PASS | boilerplate prefilled; strip green→red→green; Publish **disabled** while JSDoc broken; on `400` a toast *"Publish failed (1 error) — see error markers"* plus a line-anchored Monaco marker (`line 14: Type 'Document' is not assignable to type 'number'`); on success *"Published v1"* → `/dynamic-nodes/:slug` |
+| 14.8 In-canvas custom node | ✅ PASS after a fix / ⚠️ one gap | auto-drop was broken — see D-10. Deleted lineage: red **DELETED** badge, settings *"(deleted dynamic node)"*, validator *"Activity type 'dyn.walk-14-8-node' is not registered"* — but **Try is not disabled**, see D-11 |
+| 14.9 Execute (Try) | ⚠️ PARTIAL | the node really ran — both nodes `succeeded` through Temporal + deno-runner via the UI. The **preview does not show the value**, and says something untrue — see D-12 |
+| 14.10 Runtime errors | ✅ PASS | full typed-error matrix green against the live runner (14/14, `RUN_INTEGRATION=1`): timeout → `DynamicNodeTimeoutError`, 6MB stdout → `StdoutTooLarge`, throw → `RuntimeError` w/ stderrTail, bad JSON → `OutputInvalidJson`, missing port → `OutputShapeError` |
+| 14.11 🔒 Net egress | ✅ PASS | `allowNet:[]` → `NotCapable: Requires net access to "example.com:443"`; allowlist the host → `exit 0 {"status":200}`. The allowlist **is** the gate |
+| 14.12 🔒 Remote import | ✅ PASS | `Requires import access to "blocked.example.com:443"` — no outbound fetch |
+| 14.13 🔒 Env isolation | ✅ PASS | `Deno.env.get("PATH")` → `NotCapable: Requires env access to "PATH"` |
+| 14.14 Restore-on-republish | ✅ PASS | re-POST after soft-delete → `201 v3` (history continued, not a fresh v1), `deletedAt:null`, versions `[3,2,1]`; re-POST while live → `409 DUPLICATE_SLUG` |
+
+---
+
+## D-9 — the plan's own 14.1 example cannot publish (doc defect, fixed)
+
+The `curl` body in 14.1 declares `dynamicNode(ctx, params)` with no parameter
+types. `deno check` runs under `noImplicitAny`, so the very first thing anyone
+following Part 14 does fails:
+
+```
+400 ts-check line 8: Parameter 'ctx' implicitly has an 'any' type.
+```
+
+Everything downstream cascades — 14.3 `400`, 14.4/14.5 `404`, 14.14 unreachable
+— because the lineage is never created. Both real sources of truth (the editor
+boilerplate and `seed-feature-demos.mjs`) type their parameters; only the plan
+does not. With a correctly typed script the whole chain passes on the first run.
+
+## D-10 — publishing a custom node never dropped it on the canvas (fixed, `64d86d73`)
+
+14.8's headline behaviour. The palette modal publishes, closes, toasts
+*"Published v1"* — and the canvas is unchanged. `addDynamicNode` looks the new
+`dyn.<slug>` up in the merged catalog and returns silently when absent, and it
+was absent for two independent reasons: the publish mutation fired
+`invalidateQueries` without returning the promise (so `mutateAsync` resolved a
+round-trip early), and even once awaited, React has not re-rendered at that
+instant — so a closed-over array *and* a ref updated during render are both a
+commit behind. Reads the TanStack cache first now. Verified live: 4 → 5 nodes.
+
+## D-11 — Try stays enabled on a graph that cannot run (open — needs a ruling)
+
+A workflow whose `dyn.*` lineage has been soft-deleted is correctly diagnosed:
+red **DELETED** badge, settings alert, and `1 error — Activity type
+"dyn.walk-14-8-node" is not registered`. But **Try and Run remain enabled**, and
+clicking Try opens the drawer as usual. Running it fails at
+`dynamicNode.resolveLineage` with `DynamicNodeDeletedError` — knowable at author
+time, which is what the *"Fail before the run"* invariant asks for.
+
+14.8 states the criterion as "Try disabled". Not fixed unilaterally because the
+scope is a product decision: **does any validation error disable Try/Run, or
+only errors that make the graph structurally unrunnable?** Those are very
+different products. Needs Alex.
+
+> ⚠️ Method note: my first reading of this said "Valid, Try enabled" and was
+> **wrong** — I sampled at 3.2s while the activity catalog was still loading,
+> and `isRegisteredActivityType` deliberately gives `dyn.*` the benefit of the
+> doubt until it resolves. At 6.5s the error is there. Any check touching
+> `dyn.*` validation must wait for the catalog.
+
+## D-12 — a succeeded dynamic node previews an untrue message (open)
+
+After a green run, the dyn node's preview reads:
+
+> Preview unavailable — cache evicted. Re-run to repopulate.
+
+Both halves are wrong. Nothing was evicted, and re-running will *never*
+repopulate it: the node is `@deterministic: false` (the default — the signature
+card even says **NON-DETERMINISTIC (NOT CACHED)**), and §3.3 says such scripts
+must re-execute every run and are deliberately not cached. So the widget offers
+an action that cannot work, for a reason that never happened.
+
+14.9's "preview shows the uppercased URL" therefore holds only for a
+`@deterministic: true` node. The honest message is "not cached — this node is
+non-deterministic", which needs the widget to see the entry's `deterministic`
+flag.
+
+## D-13 — the script editor loads Monaco from a public CDN (open)
+
+The only external request the app makes:
+
+```
+GET https://cdn.jsdelivr.net/npm/monaco-editor@0.55.1/min/vs/loader.js
+```
+
+In this sandbox it fails with `ERR_CERT_AUTHORITY_INVALID` — TLS interception,
+exactly what a government network does — and the editor sits on **"Loading…"
+forever**: no error, no timeout, no fallback, and **Publish stays enabled**, so
+you can publish the untouched boilerplate without noticing. I did that twice by
+accident before spotting it.
+
+Nothing blocks it in deployment (the frontend nginx sets no CSP), so whether the
+authoring surface works depends entirely on each user's network reaching
+jsdelivr. `monaco-editor@0.55.1` is already in `node_modules` at the exact
+version served, so the fix is `loader.config({ monaco })` against the local
+package. Not done here because it changes the build and needs the dependency
+declared — Alex's call.
+
+For the walkthrough I served the byte-identical local copy via a Playwright
+route so the 14.7/14.8 editor checks could run.
+
+---
+
+## Artifacts created (safe to delete)
+
+| Kind | Name / id |
+|---|---|
+| Library workflow | `WALK-7.8 typed ports` — `cms3tqu3z0000f2gc1b04jxz2` |
+| Workflow | `WALK-14.8 deleted-badge probe` — `cms3v1qds000hf2gcesg9ucy3` |
+| Workflow | `WALK-14.9 dyn execute probe` — `cms3v9c0x000kf2gcn1w3dtqn` |
+| Dynamic node | `uppercase-url` (v3, live) |
+| Dynamic node | `walk-14-7-node` (v1, live) |
+| Dynamic node | `walk-14-8-node`, `my-custom-node` (soft-deleted) |
+
+## Still unwalked
+
+Parts **4, 10, 11, 12, 13, 15, 16** in full, plus the open checks in Parts 3, 5,
+6, 7, 8, 9. Part 15 additionally needs cloud credentials.