PiCloud/examples/cms-poc/FINDINGS.md

# PiCloud CMS PoC — Findings Log

Running log of gaps, inconsistencies, surprises, and issues encountered while building a WordPress-inspired CMS on PiCloud. Each entry is tagged **[PiCloud]** (platform gap/footgun/bug) or **[CMS]** (our own code). Security findings live in [SECURITY.md](SECURITY.md).

Severity: 🔴 blocker · 🟠 significant · 🟡 minor/ergonomic · 🔵 note/observation

## Re-verification — `fix/cms-poc-findings` (2026-07-18)

A platform agent fixed the actionable findings. I rebuilt `picloud` + `pic` on
that branch, redeployed the CMS onto the same DB, ran a **12/12 regression
sweep** (all existing flows green), then verified each fix live and re-ran the
async chains. **All 7 fixes confirmed; no regressions.**

A **second round** then closed the two actionable workflow findings (**F-037**
reachability, **F-038** `workflow::run_status`). Both verified live, and the CMS
was refactored to **adopt** `workflow::run_status` — the `wfruns` KV / `wf_lib`
run-tracking workaround is now deleted (see the F-037/F-038 rows below).

| Finding | Fix | Live re-verification |
|---|---|---|
| **S-01/S-12/F-011** 502 info-leak | shared `scrub_runtime_detail` now also on the user-route (inbox) path | ✅ `throw #{…"SECRET_INTERNAL_MARKER"…}` on a user route → client got `{"error":"script execution error (ref: <uuid>)"}` (502), **no** marker / app-id / line / func; server log kept the full detail under the same `correlation_id` |
| **F-015** docs array-membership | `$contains` (JSONB `@>`) | ✅ rewrote `posts_list` to `tags: #{ "$contains": tag }` — DB-side filter with real `$limit`: `picloud`→3, `meta`→1, `comments`→1, `nope`→0 |
| **F-026** JSON-only bodies | content-type-aware bodies (form→object, `text/*`→string, binary→base64) + `body_base64` responses | ✅ raw `--data-binary` PNG upload stored byte-exact; `media_get` now serves **real** `image/png` bytes (cmp = equal); form-urlencoded login → 200+token; bad JSON still 400 |
| **F-030** no CORS | per-app allow-list (`pic apps cors set`), Origin echo + OPTIONS preflight; migration 0077 | ✅ default-off preserved; matching Origin echoed; preflight → **204** with `allow-methods/headers/max-age`; foreign origin **not** echoed |
| **F-012** no role CLI | `pic users add-role` / `rm-role` + admin API | ✅ granted `author` to a reader and revoked it, verified via the users API |
| **F-006** opaque apply 404 | actionable message | ✅ `app not found: ghost-app-xyz — apply does not create apps; create it first with \`pic apps create ghost-app-xyz\`…` |
| **F-021** interceptor "unreachable" warning | interceptor bindings count as reachability | ✅ `plan` no longer warns that `comment_sanitize` has no route/trigger |
| **F-037** workflow-step "unreachable" warning | reachability set also counts `[[workflows]]` step functions | ✅ `plan` emits **zero** warnings for the five `wf_*` step scripts |
| **F-038** workflow runs unobservable from a script | new read-only `workflow::run_status(run_id)` SDK (app-scoped) | ✅ **adopted** — deleted the `wfruns`/`wf_lib` workaround; `pipeline_run` reads `run_status` directly. Happy path → all `succeeded`/`completed`; gated path → `skipped`/`blocked`, post stayed draft; foreign run id → `()`/404 |

**New finding from re-testing** (a small consequence of the F-026 fix):

### F-035 🟡 [CMS] F-026 shifts body-shape validation into every script
Now that non-JSON bodies reach the script (text→string, binary→base64), an
endpoint that *assumes* `ctx.request.body` is a map will **throw → 502** if a
client sends `text/plain`/binary. Observed: `text/plain` to `/cms/auth/login`
(which did `body.email`) → 502 (correctly scrubbed, but a needless error).
Pre-fix, the platform rejected the non-JSON body at 400 before the script ran.
**Fix in-CMS:** guard `if type_of(b) != "map" { return 400 }` on JSON endpoints
(applied to `login`; `register`/`media` already did). Attribution [CMS], but a
note for the platform: the extra flexibility moves content-type discipline onto
every author — a per-route "expected content types" declaration could help.

The remaining open items are the ones the fix agent **deliberately deferred**
(documented, not regressions): S-02 platform per-row authz (fundamental design;
its 502 amplifier is now removed), F-011 throw-as-envelope semantics (scrub-only
by choice), F-034 wildcard SSE topics, S-09/S-10 platform auth rate-limit &
httpOnly cookies, F-002 `pic`/groff name clash, F-022 version skew.

---

## Summary — the findings that most affect building on PiCloud

**Most significant friction (🟠):**
- **F-006** `pic apply` can't create an app — only groups; the first deploy needs `pic apps create` first.
- **F-007** `/api/` (and `/admin/`) are reserved route prefixes — the obvious REST layout is rejected; namespace elsewhere.
- **F-011** `throw #{statusCode}` becomes a **502 that leaks the app id + script internals** — the response-envelope convention is *return-only*; a footgun for authz aborts (and an info-leak — see SECURITY S-01).
- **F-012** No CLI/API to grant an app-user a role — role assignment is script-only; you must build a bootstrap endpoint.
- **F-015** The docs filter DSL **can't match membership inside an array field** (no `$contains`/`@>`) — "posts with tag X" isn't expressible.
- **F-026** User routes are **JSON-in/JSON-out only** — no form posts, no raw binary uploads, no binary responses.
- **F-030** **No CORS** and no config for it — a cross-origin SPA can't call the API; you must reverse-proxy or bundle same-origin.

**Ergonomic gaps (🟡):** F-001 (SMTP env vars ≠ docs), F-004 (`host_kind`/`path_kind` enum values), F-005 (inline `[vars.env]` silently misparses), F-008 (kebab-only var keys), F-017 (docs envelope shape), F-019/F-020 (interceptor is per-service not per-collection, create-only), F-029 (DSL timestamp compare is lexical), F-034 (SSE topics are concrete-only).

**Genuine strengths (🟢):** F-010 (plan compiles Rhai server-side), F-013/F-014 (`users::` + roles, module imports), F-016 (`set_if` CAS + kv index), F-018 (docs `before` interceptor transform), F-023/F-028 (docs→queue→email + cron trigger chains), F-031 (env overlays + safe `--prune`), F-032 (one script → many routes), F-033 (pub/sub → public SSE). Plus SDK security wins: **S-06** (email header injection prevented), **S-07** (SSRF blocked by default), **S-08** (secrets never plaintext).

**Headline security posture:** a public route holds **full app authority** with **no per-row authz** (S-02), and uncaught errors **leak internals via 502** (S-01). Every access decision is app code; one missing `guard()` is a silent full bypass. See [SECURITY.md](SECURITY.md).

---

## S0 — Infra & environment

### F-001 🟡 [PiCloud] SMTP relay env vars differ from documentation
**What:** To relay `email::send` through a real SMTP server (Mailpit), the docs / CLAUDE.md and onboarding notes suggested `PICLOUD_SMTP_HOST/PORT/FROM/USERNAME/PASSWORD/REQUIRE_TLS`. The **actual** env vars (crates/manager-core/src/email_service.rs:208-236) are:
- `PICLOUD_SMTP_HOST`, `PICLOUD_SMTP_USER`, `PICLOUD_SMTP_PASSWORD` — **all three required** or the relay stays disabled (falls back to dev capture sink).
- `PICLOUD_SMTP_PORT` (default 587/465 depending on TLS), `PICLOUD_SMTP_TLS` (`implicit`/`starttls`/`none`), `PICLOUD_SMTP_TIMEOUT_SECS`.
- **There is NO `PICLOUD_SMTP_FROM`** — the sender is taken from each `email::send(#{ from })` call. **`USER` not `USERNAME`; `TLS` not `REQUIRE_TLS`.**

**Impact:** Setting `PICLOUD_SMTP_HOST/PORT/FROM` alone (as the docs imply) silently leaves email in dev-capture mode — the log line `email DEV CAPTURE ...` is the only signal. Confusing for a first-time operator.

**Surprise/why it matters:** the relay is all-or-nothing on three vars, and one of the "documented" vars (`FROM`) doesn't exist while the SDK requires `from` per-call. For Mailpit (no TLS, accepts any auth) the working combo is:
`PICLOUD_SMTP_HOST=127.0.0.1 PICLOUD_SMTP_USER=x PICLOUD_SMTP_PASSWORD=x PICLOUD_SMTP_PORT=1025 PICLOUD_SMTP_TLS=none`.

### F-002 🔵 [PiCloud] CLI binary name collision with groff
**What:** The PiCloud CLI builds as `pic`, but `/usr/bin/pic` on this host is **groff's** `pic` (picture preprocessor). A naive `pic ...` invocation runs groff, not PiCloud. Had to use `./target/debug/pic` explicitly. Minor, but a packaging/name-collision worth noting for a tool meant to be installed on developer machines.

### F-003 🔵 [PiCloud] No per-kind `docs`/`pubsub`/`email`/`queue`/`files` trigger CLI wrapper
**What:** `pic triggers` only has per-kind create wrappers for some kinds; docs/files/pubsub/email/queue triggers must go through `pic triggers create-from-json` OR the declarative manifest. Fine for us (we use the manifest), but noted: the imperative CLI is not at parity with the declarative surface.

### F-004 🟡 [PiCloud] `host_kind` / `path_kind` enum values are non-obvious
**What:** Route `host_kind` values are `any` / `strict` / `wildcard` (NOT `exact`), and `path_kind` values are `exact` / `prefix` / `param` (NOT `pattern`/`regex`). Several summaries/docs say `host_kind = "exact"` or `path_kind = "regex"`, which fail `deny_unknown_fields`/enum parsing. Path parameters (`:slug`) require `path_kind = "param"` — using `exact` with a `:slug` in the path would match the literal string `:slug`, not capture it. (Source: crates/shared/src/route.rs:14-38.)

---

## S1 — Skeleton apply & routing

### F-005 🟡 [PiCloud] Env overlays are separate files; inline `[vars.<env>]` silently misparses
**What:** `pic apply --env dev` merges a **separate** `picloud.<env>.toml` overlay file. Putting `[vars.dev]` inline in the base `picloud.toml` does NOT create a dev-env overlay — because the base `vars` field is a `map<string, toml::Value>`, `[vars.dev]` parses as a var literally **named `dev`** whose value is a table. No error is raised; it just silently produces a bogus var. Overlay files may carry `[app]` (slug/name), `[secrets]`, `[vars]`. **Footgun:** the natural inline form is silently wrong.

### F-006 🟠 [PiCloud] `pic apply` cannot CREATE an app — only groups
**What:** The declarative tree apply (`/tree/apply`) reconciles the group tree SHAPE (creates groups) but for an app node calls `resolve_app`, which throws `AppNotFound` if the app doesn't exist (apply_service.rs:3358-3366). So the *very first* deploy of an app fails with `HTTP 404: app not found: cms` until you run `pic apps create <slug>` imperatively. `pic init` scaffolds the manifest but does not create the app. **Surprise:** contradicts the "declarative, one-command" framing — the app is a manual prerequisite; only groups are declaratively creatable. Also: a `[project]` block over a bare app (no group) shows `ownership: unclaimed` at plan and is effectively **inert** — apps are only claimed via a nearest-ancestor *group*, so single-app repos can't exercise ownership at all.

### F-007 🟠 [PiCloud] `/api/` and `/admin/` are reserved route prefixes — a headless-CMS gotcha
**What:** User routes may not start with `/api/`, `/admin/`, `/healthz`, `/version` (422 `path ... is reserved`). The instinctive REST layout (`/api/posts`, `/api/admin/posts`) is rejected wholesale because `/api/` is the platform control plane. Had to namespace the whole CMS under `/cms/...`. **Impact:** any app modelling itself as an HTTP API must avoid the single most conventional prefix; the reservation is a hard, instance-global rule not scoped per app/host.

### F-008 🟡 [PiCloud] `vars` keys are kebab-case only (`[a-z0-9-]`, no underscores)
**What:** A var key like `comment_moderation` is rejected: "must be 1–128 chars of lowercase letters, digits, and hyphens, starting with a letter or digit." So `site_title`, `posts_per_page`, etc. are all invalid — must be `site-title`, `posts-per-page`. Meanwhile Rhai **map literal keys** can't contain hyphens (parsed as minus), so the two namespaces diverge: `vars::get("site-title")` (kebab string) feeding a Rhai field `site_title:` (snake identifier). Mildly confusing; easy to trip on. (Secrets, by contrast — see later — and script/route names have their own rules.)

### F-009 🔵 [PiCloud] A new app's routes 404 until it claims the request Host
**What:** Two-phase dispatch resolves Host→app first (most-specific domain claim wins; `Any` matches everything, `Strict` beats it). A freshly-created app has **no** domain claim, so every route 404s (`no route matches GET /cms/hello`) even though `pic apply` reported the route created. The seeded **`default`** app claims `localhost` (exact), so on a dev box `localhost:8081` resolves to `default`, and a new app is unreachable there until you *move* or *add* a host claim. This IS documented in `pic apps domains --help`, but it's an easy-to-miss step between "apply succeeded" and "route works." Resolution for this PoC: `pic apps domains rm default <id>` + `pic apps domains add cms localhost`.

### F-010 🟢 [PiCloud] positive: `pic plan` compiles Rhai server-side
**What:** `pic plan`/`apply` compile every script's Rhai source on the server and reject syntax errors at plan time (`invalid script source: Expecting ':' ... (line 6, position 13)`), with line/column. Nice — you catch a broken script before it's deployed, not at first request. (Minor CLI nit: `pic routes ls` takes a positional `SCRIPT_ID`, not `--app`, unlike most other `ls` commands which accept `--app`.)

---

## S2 — Auth (app-users + roles)

### F-011 🟠 [PiCloud] `throw #{ statusCode }` becomes a 502 that leaks internals — envelope convention is return-only
**What:** The response-envelope convention (`#{ statusCode, headers, body }`) applies ONLY to a **returned** value. **Throwing** the same map does not produce that HTTP status — the executor treats it as an uncaught runtime error and returns **HTTP 502** with a body like:
`{"error":"Runtime error: #{\"body\": #{\"error\": \"unauthenticated\"}, \"statusCode\": 401} @ 'app:2cced4ba-...-...' (line 43, position 18)\nin call to function 'require_user' ... (line 3, position 15)"}`
**Two problems:** (1) the intuitive `throw #{statusCode:403}` for authz aborts is silently a 502, not a 403; (2) the 502 body **leaks the app UUID, function names, and line/column** of the script (info disclosure — see SECURITY S-01). **Mitigation in this CMS:** a non-throwing `auth::guard()` that RETURNS `{ok,response}`; the caller returns `g.response`. Any endpoint author reaching for `throw` to signal an HTTP error will get this wrong.

### F-012 🟠 [PiCloud] No CLI/API to grant an app-user a role — role assignment is script-only
**What:** `pic users` can list/inspect users, mint reset tokens, revoke sessions — but there is **no** command (nor admin HTTP endpoint) to add/remove an app-user *role*. `users::add_role` exists only inside Rhai. So bootstrapping the very first admin/author requires writing a dedicated **script** endpoint (here `auth_bootstrap`, gated by a `setup-token` secret). An operator cannot promote a user from the outside; every role change must be mediated by app code. Ergonomic gap for an admin/RBAC-heavy app.

### F-013 🟢 [PiCloud] positive: the `users::` app-user system is solid & ergonomic
**What:** `users::create/login/verify/logout/has_role/add_role/email_available` all behaved exactly as documented, returning `()` for absent and tokens/bools cleanly. `email_available` is the anon-safe probe; `login` returned a session token; `verify` round-tripped the user with a sliding TTL. Roles composed nicely. This is the strongest part of the SDK for building an auth layer — the app-user tier being distinct from platform admins is the right model for a CMS's readers+authors.

### F-014 🟢 [PiCloud] positive: `import "<module>" as m` + module funcs calling the SDK works
**What:** A `kind=module` script (`auth`) imported via `import "auth" as auth;` and its functions call `users::*` freely; `ctx` is passed in as a parameter (modules don't capture caller scope). The shared access-boundary module pattern works as intended.

---

## S3 — Posts (docs + kv index + CAS)

### F-015 🟠 [PiCloud] docs filter DSL cannot match membership inside an array field
**What:** `docs::find` builds SQL via `jsonb_extract_path_text(data, 'field')`, which for an **array** field returns the array serialized as compact JSON text (docs_repo.rs:378-380). So a filter like `#{ tags: #{ "$in": [tag] } }` compares the tag against the *whole serialized array string* (`["intro","picloud"]`), never element membership. There is **no `$contains` / `@>` / array-element operator**. **Impact:** the single most common blog query — "posts with tag X" — isn't expressible in the DSL. Worked around by fetching published posts and filtering in Rhai (breaks true pagination) — or you'd maintain a separate kv/docs index. A JSONB containment operator would close this cleanly.

### F-016 🟢 [PiCloud] positive: `set_if` CAS + kv index pattern works well
**What:** The CAS view counter (`kv::set_if(key, expected, new)` in a bounded retry loop) incremented correctly under repeated hits (1→2→3), and the `slugs` kv collection as an O(1) slug→id index worked cleanly for public post URLs. `$sort`/`$limit` on scalar fields (status, updated_at, publish_at ISO strings) behaved as documented. Solid primitives for the read/index paths.

### F-017 🟡 [PiCloud] docs stores return an ENVELOPE, not the bare doc — easy to double-nest
**What:** `docs::get`/`find` return `#{ id, data, created_at, updated_at }` with the user's fields under `.data`. It's easy to accidentally return the envelope (leaking the wrapper) or to double-nest. Combined with the response-map convention (a returned map with no `statusCode` becomes the whole body), a script that does `return doc;` ships `{id, data:{...}, ...}` to the client. Not a bug, but a shape mismatch you must normalize (`shape_doc`) on every read path.

---

## S4 — Comments + sanitization interceptor

### F-018 🟢 [PiCloud] positive: `before` docs interceptor transform works end-to-end
**What:** A `[[interceptors]] service="docs" ops=["create"] phase="before"` hook receives the op-context (`{service, op, collection, key, value}`) **as its request body** and returns `#{ allowed: true, data: <rewritten value> }`. Verified: a comment body containing `<script>`, `<img onerror>`, `&`, and an `<b>` author_name were all HTML-escaped **before** persistence, and the moderation status was set from a `vars` value — all transparently to the `comment_create` endpoint. Fail-closed verdict (only `#{allowed:true}` allows; a dangling/erroring hook denies) is the right default for a security control. This is a genuinely nice feature for centralised write-time sanitization/validation.

### F-019 🟡 [PiCloud] interceptors bind per-SERVICE+op, not per-collection — needs an in-hook guard
**What:** The docs `create` interceptor fires for **every** docs collection (posts, pages, comments). The hook must branch on `p.collection` and no-op on the rest, or it would rewrite unrelated writes. Verified a post body `if a < b && b > c {}` is preserved only because the hook guards `collection != "comments"`. Also every post/page create now pays an extra script execution. A per-collection binding (or a `collection_glob` like triggers have) would be more ergonomic and less error-prone.

### F-020 🟡 [PiCloud] `ops=["create"]` doesn't cover UPDATE — sanitization gap on edits
**What:** The comment interceptor guards `create` only; a later `docs::update` to the same comment is **not** re-sanitized. Our admin moderation only flips `status` (safe), but any feature that edits a comment/post body through `update` would bypass the escaper. You must remember to also register a `phase="before" ops=["update"]` hook. Easy to overlook; the "sanitize on write" mental model doesn't map cleanly to create-vs-update.

### F-021 🔵 [PiCloud] plan warns an interceptor script "has no route or trigger"
**What:** `pic plan` prints `warning: endpoint 'comment_sanitize' has no route or trigger — only reachable via the execute-by-id bypass / invoke()`. But it IS reachable — as an interceptor. The reachability check doesn't count an `[[interceptors]]` binding, so a legitimately-bound hook looks orphaned. Cosmetic, but could mislead you into "cleaning up" a live hook.

### F-022 🔵 [env] the shipped `pic`/`picloud` 1.1.9 binaries lagged the source
**What:** The pre-installed `target/debug/pic` (self-reported `pic 1.1.9`) **rejected** the `[[interceptors]]` manifest block (`unknown field 'interceptors'`) though the source at `crates/picloud-cli/src/manifest.rs` supports it. A rebuild fixed it — but the version string stayed `1.1.9` across both, so nothing signals the skew. A build/version that doesn't bump when the manifest schema changes makes "which features does my CLI actually support?" unanswerable from `--version`.

---

## S5 — Notifications (docs-trigger → queue → email → Mailpit)

### F-023 🟢 [PiCloud] positive: the docs-trigger → queue → email chain is robust and fast
**What:** Publishing a post fired the whole 3-hop async pipeline — `posts_on_publish` (docs trigger) → `queue::enqueue` → `notify_drain` (queue trigger) → `email::send_html` → Mailpit — delivering one email per reader (4/4) in **~1 second**, from the configured `notify-from-email`. The transactional-outbox dispatch, the publish-transition detection (`prev_data.status`), chunked enqueue, and the SMTP relay all worked first try. This is the most complex integration in the CMS and it was the smoothest — the event/trigger model is a genuine strength. Retry/dead-letter config (`retry_max_attempts`) is declarative per trigger.

### F-024 🔵 [PiCloud] `ctx.event.docs.prev_data` makes transition detection clean
**What:** The docs trigger event carries both `data` and `prev_data`, so "became published" is a simple `data.status=="published" && prev_data.status!="published"`. On a draft create (`prev_data == ()`) and on non-status updates it correctly no-ops. Good event ergonomics.

### F-025 🔵 [CMS] rate-limiter shares one bucket when `x-forwarded-for` is absent
**What:** Our register/comment rate limiter keys on `ctx.request.headers["x-forwarded-for"]`, which is absent on direct `curl` to the origin, so every local client shares the `"local"` bucket — a 6th local registration in an hour is throttled (429). Behind Caddy the header would be set per-client. **Attribution [CMS]**, but note **[PiCloud]**: there is no built-in client-IP surface in `ctx` (no `ctx.request.remote_addr`), so an app behind no proxy has no reliable per-client key for rate limiting — you depend entirely on a trusted upstream setting XFF. A spoofable `x-forwarded-for` from an untrusted client would also let an attacker rotate the bucket (see SECURITY).

---

## S6 — Tags, media (files), cron scheduled-publish

### F-026 🟠 [PiCloud] user routes are JSON-in/JSON-out — non-JSON request bodies are rejected
**What:** The dispatch path does `serde_json::from_slice(&body_bytes)` and returns 400 `invalid JSON body` for any non-empty body that isn't valid JSON (orchestrator-core/src/api.rs:261). So a user route **cannot** accept `application/x-www-form-urlencoded`, `text/plain`, or **raw binary** — a classic HTML `<form>` POST or a file upload with a binary body is rejected before the script runs. This contradicts the "body is a String if not application/json" description. **Impact:** file uploads must be **base64-in-JSON** (done here), inflating payloads ~33% and capped by the 10 MiB body limit; and you can't build a no-JS HTML form that posts directly to a route. Likewise responses: there's no way to stream raw bytes back (media is returned as base64 for the frontend to turn into a `data:` URL — fine for a PoC, wrong for real media serving).

### F-027 🟢 [CMS] SVG upload rejected to prevent stored XSS
**What:** `media_upload` allowlists `image/{png,jpeg,gif,webp}` and rejects `image/svg+xml` (415), because an SVG served same-origin can execute embedded `<script>`. Verified. Attribution [CMS] — but note **[PiCloud]**: `files::` performs no content sniffing/validation and `media_get` would happily hand back whatever `content_type` was stored, so the allowlist is entirely the app's responsibility.

### F-028 🟢 [PiCloud] positive: cron + trigger-fires-trigger chain works
**What:** A 6-field cron trigger (`0 * * * * *`) flipped a due `scheduled` post to `published` within the minute; that `docs::update` then fired the `posts_on_publish` docs trigger → queue → 4 notification emails. The full cron→docs→queue→email chain (a trigger firing a trigger) ran cleanly and stayed within the depth bound. Both `files::` (create/head/get round-tripped a 75-byte PNG byte-exact) and cron behaved as documented.

### F-029 🟡 [PiCloud] docs DSL `$lte` on ISO-timestamp strings works only because ISO-8601 sorts lexically
**What:** `posts_scheduled_publish` filters `publish_at: #{ "$lte": now }` where `now = time::now()` (ISO string). This works because `jsonb_extract_path_text` compares text and ISO-8601 is lexically ordered — but it's an implicit contract: any non-lexicographic timestamp format (epoch millis as a number, `time::now_ms()`) would compare as **text** and silently mis-order. There's no typed/temporal comparison in the DSL; correctness rides on always storing zero-padded ISO strings.

---

## S8/S9 — Frontend, env overlays, prune

### F-030 🟠 [PiCloud] No CORS support — a decoupled SPA can't call the API cross-origin
**What:** User routes send **no** `Access-Control-Allow-Origin` (or any CORS) header, and there's no config to enable CORS. A browser SPA on a different origin (`:5173`) is blocked from calling the API on `:8081`. For a platform whose selling point is "upload scripts, get HTTP endpoints" consumed by a frontend, this forces either (a) same-origin bundling behind Caddy, or (b) a dev/prod reverse proxy. Worked around with Vite's `server.proxy` (`/cms` → `:8081`), which also sidesteps CORS **preflight** (same-origin to the browser). Also relevant: OPTIONS isn't a routable method here, so a genuine cross-origin preflight would 404 regardless. A `cors_allowed_origins` per-app setting would make the headless-CMS story first-class.

### F-031 🟢 [PiCloud] positive: env overlays + prune are solid and safe
**What:** `pic plan --env prod` cleanly showed only the overlaid vars (`site-base-url`, `signups-open`) as `update / value changed`, leaving the rest `noop`; the dev overlay was live (`site_base_url = http://localhost:5173`). `--prune` correctly diffed a removed script+route as `delete`, and **refused to run non-interactively without `--yes`** ("prune deletes resources … cannot be undone. Review with `pic plan`, then re-run with `--yes`") — a good guardrail. After `--prune --yes` the throwaway route 404'd and the rest of the app was untouched. The declarative reconcile loop (plan → apply → prune) is the strongest part of the tooling.

### F-032 🟢 [PiCloud] positive: one script bound to many routes works
**What:** The `pages` and `comments_admin` scripts are each bound to several `[[routes]]` (different methods/params) and dispatch internally on `ctx.request.method` + path — a clean way to build a REST resource without one script per verb. `ctx.request.params` populated correctly across `param` routes (`/cms/pages/:slug`, `/cms/admin/pages/:id`).

---

## S7 — Live comments (pub/sub + realtime SSE)

### F-033 🟢 [PiCloud] positive: pub/sub → SSE realtime works cleanly, incl. anonymous public topics
**What:** Approving a comment fires `comment_on_approve` (docs trigger, `update`) → `pubsub::publish_durable("comments-feed", …)` → the registered **external, `auth_mode=public`** topic streams to any SSE subscriber. Verified end-to-end via `curl -N /realtime/topics/comments-feed` (event arrived ~3s after approval) AND through the Vite dev proxy to the browser `EventSource`. `pic topics create --external --auth-mode public` makes a topic anonymously subscribable — exactly right for a public live-comment feed (no per-viewer token needed). The durable-publish + broadcast split (durable outbox fan-out, then live broadcast) is a nice model.

### F-034 🔵 [PiCloud] SSE topics are concrete (no wildcards) — per-entity live feeds need a shared topic + client filter
**What:** Registered topics must be concrete names (no `*`), so a per-post topic (`comments.<id>`) isn't registerable dynamically. Used one shared public `comments-feed` topic carrying `post_id` and filtered client-side. Fine for public comments, but a per-entity **private** live feed would need `auth_mode=token` + a minted `subscriber_token` scoped per topic — and you'd still need a concrete registered topic per entity, which doesn't scale to unbounded ids. A wildcard/prefix topic registration would help. (`subscriber_token` also requires an authenticated principal, so anonymous *scoped* subscriptions aren't possible — it's all-public or authed.)

---

## Workflows — editorial publish pipeline (added 2026-07-18)

Added a durable-DAG automation to dogfood the Workflows feature (the one major
PiCloud capability the original PoC skipped): `validate → (enrich ∥ seo) →
publish → finalize`, authored as a `[[workflows]]` block, started from a script
via `workflow::start`, visualized live with Svelte Flow (`@xyflow/svelte`).

### F-036 🟢 [PiCloud] positive: the Workflows engine is excellent
**What:** Declarative `[[workflows]]` DAG applied cleanly; the full 5-step run
executed in **<1s**. Verified from timestamps that `enrich` and `seo` ran **in
real parallel** (both fired ~15ms apart, after `validate`), then `publish`, then
`finalize`. Conditional `when = "steps.validate.output.ok == true"` gated the
branch: on a post with an empty body, `validate` failed and enrich/seo/publish
were **skipped**, leaving the post a draft. `{{ input.x }}` input templating and
`steps.<name>.output` references worked; `pic workflows ls/runs` shows the
history; a step's returned body becomes its `output`; steps freely called
`docs`/`kv` and the `publish` step **chained into the existing notification
pipeline** (docs-trigger → queue → 4 emails). This is a genuinely strong,
well-integrated feature — the highlight of the platform.

### F-037 🟡 [PiCloud] workflow-step scripts trip the "no route or trigger" reachability warning
**What:** A script referenced only by `[[workflows.steps]] function = "…"` is
flagged at plan/apply: `warning: endpoint 'wf_validate' has no route or trigger
— only reachable via the execute-by-id bypass / invoke()`. But it IS reachable —
as a workflow step. The F-021 fix taught the reachability check about
**interceptor** bindings but not **workflow-step** bindings, so all five step
scripts look orphaned. Same class of bug as F-021, one binding-type short.
**✅ Resolved (platform):** the reachability set now also counts `[[workflows]]`
step `function`s (and interceptor scripts). Verified live — `pic plan` on this
CMS now emits **zero** reachability warnings for the five workflow-step scripts.

### F-038 🟠 [PiCloud] workflow runs are observable only via the platform-admin API — not from scripts
**What:** `workflow::start(name, input)` is the *only* workflow SDK call — it
returns a run id but there is **no** `workflow::get_run`/status from a script.
Run status/history lives behind the platform-admin API
(`GET /api/v1/admin/apps/{app}/workflow-runs/{id}`), which needs an instance-admin
bearer token — not an app-user token. So a data-plane app **cannot surface its
own workflow progress to its own users** without either borrowing platform-admin
credentials or rolling its own run tracking. I did the latter: each step writes
progress into a `wfruns` KV store (own key per step, so `enrich ∥ seo` don't
contend), and a `/cms/admin/workflow/runs/:id` endpoint reassembles it for the
UI. It works, but "startable from a script, not observable from a script" is an
asymmetry worth closing (even a read-only `workflow::run_status(id)` would do).
**✅ Resolved (platform) + adopted:** `workflow::run_status(run_id)` shipped —
returns `#{ status, output, error, steps: #{ name: status } }` or `()` when no
such run belongs to the app (app-scoped at the SQL, the isolation boundary; same
`AppInvoke` gate as `start`). **The CMS now uses it:** the `wfruns` KV workaround
(and the `wf_lib` progress-writer module) is **deleted** — `pipeline_run` reads
`workflow::run_status` directly, and the step scripts no longer thread a
`run_id`. Re-verified live end-to-end: happy path (all 5 steps `succeeded`,
overall `completed`) and gated path (empty body → `validate` succeeded but
`output.ok=false` → enrich/seo/publish `skipped`, overall `blocked`, post stayed
draft). A run id from another app resolves to `()` → 404.

### F-039 🔵 [PiCloud] a skipped step does NOT block its dependents (skip ≠ fail)
**What:** When `publish`'s `when` is false it is **skipped**, yet `finalize`
(`depends_on = ["publish"]`) still **runs** — a skipped dependency is treated as
satisfied, not as a barrier. Reasonable, but a footgun: my first `finalize`
marked the run "completed" even though nothing was published. Fixed by having
`finalize` inspect whether `publish` actually succeeded (→ reports
"completed" vs "blocked"). Authors must not assume "my dependents only run if I
ran" — model the skip case explicitly. **Status:** confirmed **by design** and
documented — the `WorkflowStepDef.when` contract is "skipped = satisfied-but-
empty"; gate a dependent with its own `when` if it must not run on a skip. (With
F-038 resolved, `workflow::run_status` now reports an **explicit** per-step
`skipped` status from the engine, so `pipeline_run` no longer has to *infer*
skips — it still falls back to `skipped` for a step absent from a terminal run,
but the engine supplies the real marker.)

### F-040 🟢 [tooling] Svelte Flow (`@xyflow/svelte` v1) drops into Svelte 5 cleanly
**What:** `@xyflow/svelte@1.6.2` (peer `svelte ^5.25`) integrated with the
SvelteKit SPA using `bind:nodes`/`bind:edges` on `$state` arrays; a small
longest-path layout + per-status node `style` gives a live-updating DAG that
colors each node as the run progresses (polling `/cms/admin/workflow/runs/:id`).
Good fit for visualizing a PiCloud workflow.