PiCloud/CHANGELOG.md

PiCloud Changelog

v1.1.9 — Durable Queues & Function Composition (unreleased)

Per-app durable queues + same-app function composition + caller- controlled retries. The final v1.1.x release before the v1.2 phase milestone. No upgrade-order constraint — pure additive surface, no destructive migrations.

Added — queue::* SDK (durable per-app named queues)

• queue::enqueue(name, message) / queue::enqueue(name, message, opts) — write one message onto a per-app named queue. opts is a Map with delay_ms (defer delivery until NOW() + delay) and max_attempts (clamped to [1, 20]; default 3). Message is any JSON-serializable value — Maps, Arrays, scalars, and Blobs (which base64-encode at any depth, mirroring pubsub::publish_durable). FnPtr / closures are rejected at the bridge.
• queue::depth(name) / queue::depth_pending(name) — read-only inspection. depth is COUNT(*); depth_pending filters to claim_token IS NULL AND (deliver_after IS NULL OR deliver_after <= NOW()).
• Identity tuple is (app_id, queue_name). Queue names are implicit — no queue registry table, no separate "create queue" ceremony. A queue exists once the first message is enqueued under that name.
• No peek / dequeue / purge script-side surface. Consumers are triggers; exposing manual dequeue would force the platform to surface visibility-timeout semantics into script-land.
• New capability AppQueueEnqueue(AppId) (script:write scope, editor+).

Added — queue:receive trigger kind

• Exactly one consumer per (app_id, queue_name) — enforced via pg_advisory_xact_lock(hash(app_id || queue_name)) + a SELECT-then- INSERT in one transaction (a partial unique index can't span the parent's app_id from the detail table). The second create returns 422 Invalid with the message queue 'X' already has a consumer trigger; remove the existing one first.
• Per-trigger visibility_timeout_secs (clamped [5, 3600]; default via PICLOUD_QUEUE_DEFAULT_VISIBILITY_TIMEOUT_SECS). The dispatcher treats this as the lease window; a handler that holds the claim past this point loses it to the periodic reclaim task.
• Retry policy lives on the parent triggers row (the same retry_max_attempts / retry_backoff / retry_base_ms every other trigger kind reads); no duplication on the detail row.
• Surfaced to handler scripts as ctx.event.queue — { queue_name, message, enqueued_at, attempt, message_id } — plus ctx.event.source = "queue" and ctx.event.op = "receive".
• Trigger executes as the principal that registered it (matches design notes §4 — every trigger kind does this).

Added — Dispatcher queue arm + visibility-timeout reclaim task

• The queue table IS the outbox for queue semantics. The dispatcher doesn't double-buffer through outbox; it claims directly from queue_messages via the single-round-trip UPDATE … WHERE id = (SELECT id … FOR UPDATE SKIP LOCKED LIMIT 1) RETURNING …. SKIP LOCKED keeps concurrent dispatchers (cluster mode v1.3+) safe.
• Per tick (every 100ms), interleaved with the existing outbox arm: list every enabled queue:receive consumer and try one claim each. Bounded by the registered-consumer count, so one busy queue can't starve the rest.
• Auto-ack: handler returns successfully → DELETE FROM queue_messages WHERE id = $1 AND claim_token = $2. The token in the WHERE is the leasing guarantee.
• Auto-nack: handler throws → if attempt < max_attempts, clear the claim and set deliver_after = NOW() + compute_backoff(...); else, write a dead_letters row (the existing fan_out_dead_letter path then fires registered dead_letter triggers off it) and delete the queue row, in one transaction.
• Visibility-timeout reclaim: a separate tokio::spawn task ticks every PICLOUD_QUEUE_RECLAIM_INTERVAL_MS (default 30000) and clears claims older than the per-queue visibility_timeout_secs. A crashed consumer (or one whose handler hung past the visibility window) thus loses its lease and the message becomes claimable again.

Added — invoke() + invoke_async() (same-app function composition)

• invoke(target, args) — sync, returns the callee's response body as a Rhai Dynamic. target is a string (path → route trie, UUID → ScriptId, else → (app_id, name) lookup). Same engine instance and Services are reused; only the per-call SdkCallCx changes (callee gets trigger_depth + 1 and a fresh execution_id, inherits the caller's principal and root_execution_id).
• invoke_async(target, args) — fire-and-forget. Writes an OutboxSourceKind::Invoke row the dispatcher fires once (no retry loop — callers who want retries wrap in retry::run). Returns the new ExecutionId as a string for caller tracking.
• Cross-app invokes are rejected at the InvokeService::resolve layer with InvokeError::CrossApp ("invoke: target script belongs to a different app"). v1.1.x maintains strict isolation; cross-app sharing arrives in v1.3+.
• Depth-bound: cx.trigger_depth + 1 > limits.trigger_depth_max throws "invoke: depth limit exceeded (max N)" — shared with the trigger fan-out cap so a misbehaving recursive script can't blow the stack.
• FnPtr / closures in args are rejected (closures don't survive re-entry into a fresh SdkCallCx).

Added — retry::* SDK (caller-controlled retry)

• retry::policy(opts) — constructs a Policy value (custom Rhai type). Validates + clamps: max_attempts ∈ [1, 20], base_ms ∈ [1, 60_000], jitter_pct ∈ [0, 100], backoff ∈ {"exponential" | "linear" | "constant"}.
• retry::run(policy, closure) — calls closure(); on throw, sleeps per the policy and re-invokes; after max_attempts exhausted, throws the last error. Sleeps via tokio::time::sleep through TokioHandle::block_on — the bridge is already inside the caller's spawn_blocking thread.
• retry::on_codes(policy, codes_array) — returns a new policy with an error-string filter. When non-empty, only throws containing one of the codes retry; others surface immediately.
• NOTE on the brief deviation: the brief asked for retry::with, but both with AND call are Rhai reserved keywords (rejected at the parser, before registration could matter). Shipped as retry::run(policy, closure) instead. Documented in HANDBACK §7.

Added — Admin HTTP endpoints

• POST /api/v1/admin/apps/{id}/triggers/queue — create a queue:receive trigger. Body: { script_id, queue_name, visibility_timeout_secs?, dispatch_mode?, retry_max_attempts?, retry_backoff?, retry_base_ms? }. Capability: AppManageTriggers.
• GET /api/v1/admin/apps/{id}/queues — list every distinct queue name in the app with (total, pending, claimed) counts. Capability: AppLogRead.
• GET /api/v1/admin/apps/{id}/queues/{queue_name} — drill-down: stats + registered consumer trigger (if any). Capability: AppLogRead.
• No mutating queue endpoints (purge / requeue / delete-message stays at v1.2).

Added — Dashboard (v0.15.0)

• New /apps/{slug}/queues read-only list view (queue name + counts + drilldown link) and /apps/{slug}/queues/{name} drill-down (depth + registered consumer + visibility timeout + last_fired_at).
• "Queues" link added to the app-level nav between Files and Dead letters.
• Triggers tab gains a "Queue:receive trigger (v1.1.9)" form alongside cron / pubsub / email. Trigger list renders queue triggers with the queue name + visibility timeout + last_fired_at.
• TypeScript types: TriggerKind gains 'queue'; TriggerDetails gains the Queue variant. CreateQueueTriggerInput, QueueSummary, QueueConsumer, QueueDetail exported.

Changed

• Services::new signature gains queue: Arc<dyn QueueService> and invoke: Arc<dyn InvokeService> positionally after users (mirrors v1.1.8's positional append of users). with_noop_services updated.
• Limits (crates/executor-core/src/sandbox.rs) gains trigger_depth_max: u32 (default 8). The picloud binary syncs it from TriggerConfig::from_env().max_trigger_depth so the dispatcher's trigger-depth cap and the invoke depth-bound stay aligned (env var: PICLOUD_MAX_TRIGGER_DEPTH).
• Engine gains set_self_weak(Weak<Engine>) + self_arc(). The picloud binary calls engine.set_self_weak(Arc::downgrade(&engine)) right after construction so the invoke bridge can re-enter the engine synchronously. Weak so the Arc-cycle stays loose.
• register_all gains two parameters: limits: Limits and self_engine: Option<Arc<Engine>>. The invoke bridge surfaces a clear error if self_engine is None (only in harnesses that don't wire it).
• OutboxSourceKind gains Invoke; TriggerKind gains Queue; TriggerDetails gains the Queue variant; TriggerEvent gains the Queue variant with source = "queue" discriminant.
• ScriptRepository gains get_by_name(app_id, name) for the invoke() name resolution path.
• SDK schema 1.9 → 1.10.

Migrations

• 0034_queue_messages.sql — the queue_messages table with three indexes: a partial (app_id, queue_name, enqueued_at) WHERE claim_token IS NULL for the dispatch hot path, a (app_id, queue_name) for the depth queries, and a partial (claimed_at) WHERE claim_token IS NOT NULL for the reclaim scan.
• 0035_queue_triggers.sql — widens triggers.kind to admit 'queue', widens outbox.source_kind to admit 'invoke', adds the queue_trigger_details table.

F1–F5 follow-ups (carry-forward from v1.1.8)

• F1 — integration test density: four new DB-gated test binaries (crates/picloud/tests/queue_e2e.rs ×4, …/invoke_e2e.rs ×4, …/retry_e2e.rs ×3, crates/manager-core/tests/migration_queue_messages.rs ×4) + 50+ net new inline unit tests. All skip cleanly when DATABASE_URL is unset; all pass against the docker-compose postgres on localhost:15432.
• F2 — schema snapshot re-blessed via BLESS=1 cargo test -p picloud-manager-core --test schema_snapshot -- --include-ignored. Delta matches the plan exactly (no unrelated drift).
• F3 — fmt + clippy attestation as literal output: see HANDBACK §8.
• F4 — TIMING_FLAT_DUMMY_HASH dedup: inline copy in crates/manager-core/src/auth_api.rs::login now references the shared crate::auth::TIMING_FLAT_DUMMY_HASH const. grep -rn for the PHC literal returns exactly one hit.
• F5 — clippy without cold cache: incremental cache used; HANDBACK §8 notes the explicit choice.

Notes

• New env vars:
  • PICLOUD_QUEUE_RECLAIM_INTERVAL_MS (default 30000) — visibility- timeout reclaim cadence.
  • PICLOUD_QUEUE_DEFAULT_VISIBILITY_TIMEOUT_SECS (default 30) — visibility timeout fallback when the trigger create request omits one. Per-trigger column overrides this.
• SDK schema bumped to 1.10.
• @picloud/client unchanged — no client-library work this release.

---

v1.1.8 — User Management (unreleased)

Per-app data-plane user management — a users::* SDK for scripts plus an admin HTTP surface and dashboard tab — together with three load-bearing follow-ups from v1.1.7 (dropping the plaintext realtime signing-key column, --all-targets clippy discipline, and adding a session-based realtime SSE auth mode).

UPGRADE PATH IS LOAD-BEARING. v1.1.8 requires v1.1.7 to have been applied first. Operators upgrading directly from v1.1.6 or earlier MUST apply v1.1.7 (and let its startup encryption sweep complete) before applying v1.1.8 — migration 0032's guard refuses to drop the plaintext realtime_signing_key column while any row still needs encryption.

Added — users::* SDK (data-plane user management)

• users::create(#{...}) / users::get(id) / users::find_by_email(...) / users::update(id, #{...}) / users::delete(id) / users::list(#{ "$limit", cursor }) — CRUD on per-app end-users (distinct from the control-plane admin_users table). Identity tuple is (app_id, user_id); uniqueness is on (app_id, lower(email)) so the same email can exist across two apps but not twice within one. Password hash is Argon2id PHC (same algorithm as admin_users); the public AppUser record never carries the hash.
• users::login(email, password) returns a session token string, or () on bad credentials. The bad-email and bad-password branches share wall-clock cost via a timing-flat dummy Argon2id verify on email miss. Required for security, not polish.
• users::verify(token) returns the user on success (bumping the sliding TTL), () on missing / expired / revoked / cross-app.
• users::logout(token) revokes the session row.
• migrations/0026_app_users.sql + 0027_app_user_sessions.sql.

Added — Sessions

• app_user_sessions table with SHA-256 token hash, sliding TTL (PICLOUD_APP_USER_SESSION_TTL_HOURS, default 24h), hard cap (PICLOUD_APP_USER_SESSION_ABSOLUTE_HOURS, default 720h = 30d), and explicit revoked_at for logout / admin revoke-all / password- reset side-effects. Lookups reject revoked/expired rows immediately, before the weekly GC sweep runs.

Added — Email verification

• users::send_verification_email(user_id, #{ link_base, from, subject, body_template }) mints a 32-byte token, stores its SHA-256 in app_user_email_verifications, and dispatches via email::send with {link} in the body substituted for link_base?token=<raw>. EmailError::NotConfigured propagates as UsersError::EmailNotConfigured so scripts already handling the v1.1.7 email-disabled mode don't need new branches.
• users::verify_email(token) atomically consumes the one-shot token, sets email_verified_at = NOW(), emits users::email_verified.
• migrations/0028_app_user_email_verifications.sql.

Added — Password reset

• users::request_password_reset(email, #{ template }) returns Ok(()) regardless of whether the email matched — no existence-leak signal in script-land. Email-not-configured does surface (operators need to know); other email failures are silently swallowed and logged server-side.
• users::complete_password_reset(token, new_password) atomically consumes the token, updates the Argon2id hash, and revokes every active session for the user (stale tokens shouldn't ride out the reset). TTL PICLOUD_APP_USER_PASSWORD_RESET_TTL_HOURS (default 1h).
• migrations/0029_app_user_password_resets.sql.

Added — Invitations

• users::invite(email, #{ template?, display_name?, roles? }) gated on AppUsersAdmin. Omitting the template skips the email send so an admin can issue invitations for out-of-band delivery.
• users::accept_invite(token, password, display_name?) atomically consumes the invitation, creates the user with pre-staged roles applied, and mints a fresh session — caller can return both the user and the session token in one round trip. TTL PICLOUD_APP_USER_INVITATION_TTL_DAYS (default 7d).
• migrations/0030_app_user_invitations.sql.

Added — Per-app roles

• users::add_role(id, role) / users::remove_role(id, role) / users::has_role(id, role) — string-tagged, per-app. The script app decides what "admin" / "editor" / "viewer" mean. Stored in app_user_roles (composite PK so add is idempotent).
• The full AppUser record returned by every users::* getter now carries a roles array.
• migrations/0031_app_user_roles.sql.
• Role permission matrices / hierarchy / role registry are explicitly v1.2 work — v1.1.8 does not pre-commit to a model that would lock in a wrong API.

Added — Admin HTTP surface

• GET / POST / PATCH / DELETE /api/v1/admin/apps/{id}/users and /users/{user_id} — list, get, create, update, delete.
• POST /users/{user_id}/reset-password — returns a one-shot reset token in the response body (TTL 1h). No email is sent — that's the SDK's users::request_password_reset.
• POST /users/{user_id}/revoke-sessions — bulk revoke for that user.
• GET / POST / DELETE /api/v1/admin/apps/{id}/invitations and /invitations/{invite_id} — list, create, revoke pending.
• Capability gating: AppUsersRead for reads, AppUsersWrite for CRUD, AppUsersAdmin for admin-mediated verbs + invitations. All three map to existing scopes (script:read / script:write) — no new scope (seven-scope commitment).
• DTOs never include password hashes, session tokens, or unrotated reset tokens.

Added — Dashboard Users tab

• apps/[slug]/users/+page.svelte — list, create form, edit modal, revoke-sessions, reset-password (one-shot token displayed once), delete. Sub-route users/invitations/+page.svelte for pending invitations (list, create with optional inline email template, revoke).
• The main app-detail tab strip gains a Users entry above Files.
• @picloud/dashboard 0.13.0 → 0.14.0.

Changed — Realtime: drop plaintext signing-key column (F1)

• migrations/0032_drop_plaintext_realtime_signing_key.sql — guard query + ALTER TABLE app_secrets DROP COLUMN IF EXISTS realtime_signing_key. The guard refuses to apply if any row still has plaintext but no encrypted counterpart.
• v1.1.7's migrate_plaintext_keys startup task and its call from build_app are deleted; the read path now consults only the encrypted columns.

Changed — Realtime: auth_mode = 'session' (F3)

• migrations/0033_topics_auth_mode_session.sql widens the topics_auth_mode_check CHECK to allow 'session' alongside 'public' and 'token'.
• RealtimeAuthorityImpl gains a UsersService dependency; the Session branch of authorize_subscribe delegates to verify_session_for_realtime(app_id, token) (same DB lookup + sliding-TTL bump as the SDK's users::verify, but app_id is taken from the topic row, not a script).
• Dashboard Topics tab gains session as a third radio option.
• token (HMAC) validator is unchanged; both coexist per topic.

Notes

• New env vars (all with documented defaults):
  • PICLOUD_APP_USER_SESSION_TTL_HOURS (24)
  • PICLOUD_APP_USER_SESSION_ABSOLUTE_HOURS (720 = 30d)
  • PICLOUD_APP_USER_VERIFICATION_TTL_HOURS (48)
  • PICLOUD_APP_USER_PASSWORD_RESET_TTL_HOURS (1)
  • PICLOUD_APP_USER_INVITATION_TTL_DAYS (7)
• SDK schema 1.8 → 1.9 (additive surface: users::* + session topic auth mode).
• Workspace version 1.1.7 → 1.1.8.
• @picloud/client does NOT bump in v1.1.8 — its auth.login / auth.logout helpers already call dev-defined endpoints; nothing to change in the client.
• New weekly GC sweep (spawn_app_user_token_gc) prunes expired / revoked / consumed rows across the four new token tables.

v1.1.7 — Configuration & Email (unreleased)

The operational-config layer: encrypted per-app secrets, outbound email, and an inbound email trigger — plus the long-missing dead-letter handler wiring and at-rest encryption of the realtime signing key. All at-rest encryption uses a single process master key (AES-256-GCM); key rotation is deferred to v1.2.

Added — Encryption infrastructure

• Process master key from PICLOUD_SECRET_KEY (base64 of exactly 32 bytes). REQUIRED at startup — an unset or malformed key is fatal. Generate one with openssl rand -base64 32. A deterministic in-memory dev key is used ONLY when PICLOUD_SECRET_KEY is unset AND PICLOUD_DEV_MODE=true (with a prominent startup warning); there is no quiet unencrypted mode.
• picloud_shared::crypto — encrypt/decrypt envelope: Aes256Gcm, 96-bit CSPRNG nonce, 128-bit auth tag appended to the ciphertext (RustCrypto Aead layout). Both ciphertext and nonce are stored.
• Key rotation is out of scope. Changing PICLOUD_SECRET_KEY between deploys renders all existing ciphertext undecryptable. v1.2+ adds key-version columns + a re-encryption pass.

Added — Encrypted per-app secrets

• secrets::{get,set,delete,list}(name) SDK — collection-less, per-app. set accepts a String/Map/Array (JSON-encoded then encrypted); get returns the same Rhai type back; missing → (). 64 KB plaintext cap (PICLOUD_SECRET_MAX_VALUE_BYTES). migrations/0023_secrets.sql.
• Admin API GET/POST/DELETE /api/v1/admin/apps/{id}/secrets — list returns names + updated_at only, never values.
• Dashboard Secrets tab — list names + last-modified, create/update (masked value with a confirm-gated reveal), delete with confirm.
• Capability::AppSecretsRead/Write (→ script:read / script:write). No new Scope variants (seven-scope commitment). Secret writes deliberately do not emit trigger events.

Added — Outbound email

• email::send / email::send_html SDK over an SMTP relay (lettre). Config from PICLOUD_SMTP_HOST/PORT/USER/PASSWORD/TLS/ TIMEOUT_SECS; if HOST/USER/PASSWORD aren't all set the service runs in disabled mode (every send throws NotConfigured, warned at startup). Required to/from/subject + one of text/html; RFC 5322-ish address validation; 25 MB per-message cap (PICLOUD_EMAIL_MAX_MESSAGE_BYTES); reply_to defaults to from. Per-call connection (pooling deferred to v1.2); per-app from validation / SPF / DKIM are the operator's SMTP-relay concern.
• Capability::AppEmailSend (→ script:write).

Added — Inbound email (email:receive trigger)

• Webhook receiver POST /api/v1/email-inbound/{app_id}/{trigger_id} — a provider (Mailgun / Postmark / SendGrid / SES) POSTs the generic JSON shape {from,to[],cc[],subject,text,html,message_id}; the receiver verifies the optional HMAC signature, normalizes to TriggerEvent::Email, and enqueues an outbox row. 202 accepted, 401 bad/missing signature, 404 missing/wrong-kind/cross-app, 422 malformed. Handlers see ctx.event.email. migrations/0024_email_triggers.sql.
• Admin POST /api/v1/admin/apps/{id}/triggers/email + dashboard form (with the webhook URL + expected payload). The HMAC inbound_secret is stored encrypted via the master key (deviation from the original plaintext design — see HANDBACK §7).
• Provider-specific payload unmarshallers + inbound attachments → v1.2. Native SMTP listener → v1.3+.

Security/correctness fix (retroactive) — dead_letter handlers

The dead_letter trigger kind has been registerable since v1.1.1 but, due to missing dispatcher wiring (list_matching_dead_letter had no production caller), handlers have never fired. Any deploy running v1.1.1 through v1.1.6 with dead_letter triggers configured has had silently non-functional handlers. v1.1.7 fixes the wiring; existing dead_letters rows remain (no migration needed) but only NEW dead-letter events (post-v1.1.7) trigger handlers. To process older rows, use the existing admin replay surface to re-enqueue them.

Changed — Realtime signing key encrypted at rest (two-phase)

app_secrets.realtime_signing_key was stored as 32 plaintext bytes. It is now encrypted with the master key. migrations/0025_encrypt_realtime_keys.sql adds NULL-able encrypted columns and drops NOT NULL on the plaintext column; a startup task encrypts pre-existing rows; the read path prefers the encrypted columns and falls back to plaintext during the compat window. v1.1.8 will drop the plaintext realtime_signing_key column — operators should upgrade through v1.1.7 (which performs the encryption) before v1.1.8.

Notes

• New deps: aes-gcm (RustCrypto AEAD), lettre (SMTP).
• New env vars: PICLOUD_SECRET_KEY (required), PICLOUD_DEV_MODE, PICLOUD_SECRET_MAX_VALUE_BYTES, PICLOUD_SMTP_HOST/PORT/USER/PASSWORD/ TLS/TIMEOUT_SECS, PICLOUD_EMAIL_MAX_MESSAGE_BYTES.
• SDK schema 1.7 → 1.8; dashboard 0.12.0 → 0.13.0.

v1.1.6 — Realtime Channels & Client Library (unreleased)

The first external realtime surface and the first frontend library, co-shipped per the §5/§6 design-notes decisions. Browser clients can subscribe over SSE to per-app pub/sub topics that have been explicitly externalized; everything else stays internal-only. The @picloud/client TypeScript package wraps typed HTTP, SSE, auth, and React/Svelte hooks. Plus three v1.1.5 follow-ups.

Added — Realtime

• topics registry (migrations/0021_topics.sql) — pub/sub topics are internal-only by default; a topics row with external_subscribable = true opts one into external SSE subscription. auth_mode is 'public' or 'token'.
• Topic admin endpoints under /api/v1/admin/apps/{id}/topics — POST (register), GET (list), PATCH /{name} (flip external/auth_mode — its own audited surface), DELETE /{name} (unregister + disconnect live subscribers). Gated by the new Capability::AppTopicManage → app:admin scope (no new scope; the seven-scope commitment holds).
• SSE endpoint GET /realtime/topics/{topic} — data-plane surface (deliberately not under /api/). Resolves Host → app, authorizes via the RealtimeAuthority (404 for missing/internal topics, 401 for bad/absent tokens), then streams data: {topic,message,published_at} events with a configurable heartbeat (PICLOUD_REALTIME_HEARTBEAT_SEC, default 30). Token via Authorization: Bearer or ?token=.
• RealtimeBroadcaster + RealtimeEvent + RealtimeAuthority traits (picloud-shared); in-process InProcessBroadcaster (tokio::sync::broadcast, per-channel capacity PICLOUD_REALTIME_BROADCAST_CAPACITY default 64, periodic empty-channel GC) and the DB-backed RealtimeAuthorityImpl (orchestrator-core / manager-core respectively). The publish path now also fans out to in-process SSE subscribers, best-effort, after the durable outbox fan-out commits — a broadcast failure never fails the publish.
• pubsub::subscriber_token(topics, ttl) Rhai SDK (SDK schema 1.6 → 1.7) — mints an HMAC-SHA256 subscriber token (URL-safe payload.signature) scoped to externally-subscribable topics. Requires an authenticated principal + the pub/sub publish capability. TTL clamped to [10s, 24h] (default 1h), env-overridable via PICLOUD_SUBSCRIBER_TOKEN_TTL_{MIN,MAX,DEFAULT}_SEC. Per-app signing keys persist in the new app_secrets table (migrations/0022_app_secrets.sql), created lazily on first mint. No per-token revocation (rotation invalidates wholesale; short TTL is the safety mechanism).
• Dashboard Topics tab — register/list/edit/delete topics with a prominent external/internal badge, auth-mode radio (conditional on external), and a confirmation when flipping a topic external.

Added — @picloud/client (TypeScript, v1.0.0)

• New top-level package clients/typescript/ (tsup dual ESM+CJS + .d.ts, vitest). Typed HTTP via endpoint<Req,Res>(path).get()/.post() with auth-token injection and structured errors; SSE subscribe(topic, cb, {token, onTokenExpired}) with exponential-backoff reconnect, 401 token-refresh, and Last-Event-ID resume; auth.login/logout/token over dev-defined endpoints; React (useTopic/useEndpoint + PicloudProvider) and Svelte (topicStore/endpointStore) subpath exports. Optional zod/valibot runtime validation via a { parse } adapter (no hard dep). Hybrid model: no direct service access from the browser.

Changed / Fixed — v1.1.5 follow-ups

• Empty blobs accepted — NewFile::validate / FileUpdate::validate no longer reject zero-length data; empty files are a valid stored state (sentinels, placeholders). Non-breaking.
• Orphan *.tmp.* sweeper — a startup tokio task (spawn_files_orphan_sweep) walks the files root every PICLOUD_FILES_ORPHAN_SWEEP_INTERVAL_SEC (default 6h) and unlinks temp blobs older than PICLOUD_FILES_ORPHAN_TMP_TTL_SEC (default 1h). No DB cross-check (that full reconciler is v1.3+).
• Dispatcher end-to-end tests — crates/picloud/tests/dispatcher_e2e.rs, one per trigger kind (kv/docs/cron/files/pubsub/dead_letter), DATABASE_URL-gated (skip cleanly when unset).

Notes

• New deps: hmac (token signing, picloud-shared), tokio-stream (SSE body stream, orchestrator-core).
• New env vars: PICLOUD_REALTIME_HEARTBEAT_SEC, PICLOUD_REALTIME_BROADCAST_CAPACITY, PICLOUD_SUBSCRIBER_TOKEN_TTL_{MIN,MAX,DEFAULT}_SEC, PICLOUD_FILES_ORPHAN_SWEEP_INTERVAL_SEC, PICLOUD_FILES_ORPHAN_TMP_TTL_SEC.

v1.1.5 — Files & Pub/Sub (unreleased)

Two stateful services + two trigger kinds. files::* is filesystem-backed blob storage (atomic writes, path-sharded layout, single-pass SHA-256 with checksum-verified reads); the metadata row lives in Postgres, the bytes on disk. pubsub::publish_durable is durable pub/sub through the universal outbox, fanning out one delivery row per matching subscriber at publish time inside a single transaction. Both ride the v1.1.1 trigger framework as the fifth and sixth concrete kinds via the established Layout-E extension pattern.

Added

• files::collection(name).{create,head,get,update,delete,list} — blob storage SDK. create/update take a Rhai Blob; get returns a Blob (or () if missing); head/list return metadata maps (id, name, content_type, size, checksum, created_at, updated_at). create/update/delete throw on failure; get/head return () for a missing file; delete returns a was-present bool. Missing required field on create throws naming the field.
• Atomic writes — temp file → fsync → rename → fsync parent dir → DB row, so a crash never leaves a readable half-written file. SHA-256 is computed in a single pass during the write; get re-verifies it and surfaces FilesError::Corrupted (logged with the path, never auto-deleted) on a mismatch. Shard dirs are created 0o700.
• files:* trigger kind — ctx.event.files carries the metadata only (never the bytes; a handler that wants them calls files::collection(c).get(id)). prev is () on create, the prior metadata on update, the deleted metadata on delete.
• pubsub::publish_durable(topic, message) — durable publish. Message is any JSON-serializable Rhai value; Blobs encode as base64 (at any nesting depth). No matching subscriber → the publish succeeds silently with zero outbox rows.
• pubsub:* trigger kind — topic patterns are exact, <prefix>.*, or *; mid-pattern wildcards are rejected at trigger creation. ctx.event.pubsub carries topic, message, published_at.
• FilesService + PubsubService traits (picloud-shared) + FsFilesRepo/FilesServiceImpl and PostgresPubsubRepo/ PubsubServiceImpl (manager-core). Wired into the Services bundle as files and pubsub.
• Capabilities AppFilesRead/AppFilesWrite → script:read/ script:write, AppPubsubPublish → script:write. No new Scope variant — the seven-scope commitment holds. Script-as-gate: skipped when the script runs unauthenticated.
• Admin files API (GET/DELETE /apps/{id}/files) + dashboard Files view per app; Pub/Sub trigger form on the Triggers tab.
• CI — first .github/workflows/ci.yml (Postgres service, fmt + clippy + cargo test --workspace); the schema-snapshot guardrail now runs instead of being #[ignore]'d.

Changed

• Workspace version: 1.1.4 → 1.1.5
• Rhai SDK version: 1.5 → 1.6
• Dashboard version: 0.10.0 → 0.11.0
• schema_snapshot test: no longer #[ignore]'d — runs against DATABASE_URL when set, skips cleanly when absent.

Migrations

• 0018_files.sql — files metadata table (bytes live on disk).
• 0019_files_triggers.sql — widen kind/source_kind CHECKs + add files_trigger_details.
• 0020_pubsub_triggers.sql — widen kind/source_kind CHECKs + add pubsub_trigger_details + partial index.

New environment variables

• PICLOUD_FILES_ROOT (default ./data)
• PICLOUD_FILES_MAX_FILE_SIZE_BYTES (default 100 MB)

v1.1.4 — Outbound HTTP & Cron triggers (unreleased)

Two surfaces. http::* lets Rhai scripts make outbound HTTP requests (Slack webhooks, Stripe, third-party REST) fronted by an SSRF deny-list applied to the resolved IP (DNS-rebinding defense), with scheme/port restrictions, request/response body caps, and a layered timeout. Cron triggers add the fourth concrete kind on the v1.1.1 trigger framework: a scheduler task enqueues due triggers into the same universal outbox the dispatcher already drains.

Added

• http::{get,post,put,patch,delete,head,post_form,request} — outbound HTTP SDK. Body and options are separate positional args (verb(url, body, opts)); opts is {headers, timeout_ms, follow_redirects, max_redirects} (unknown keys throw). Body dispatch by type: Map/Array → JSON, String → text/plain, () → none. Response is #{ status, headers, body, body_raw } with body auto-parsed when the response is application/json. Non-2xx does NOT throw (fetch-style); network/timeout/SSRF/size errors throw with an "http: …" prefix.
• SSRF deny-list — applied to the resolved IP via a custom reqwest dns_resolver (so it covers every redirect hop and defeats DNS rebinding), plus a literal-IP check at URL-parse time. Blocks loopback, RFC1918 private, link-local (incl. 169.254.169.254), carrier-grade NAT, multicast, reserved, IPv6 ULA/link-local/loopback, and IPv4-mapped IPv6 (re-checked against the embedded v4 address). The script-visible error carries a CIDR-category reason, never the IP. PICLOUD_HTTP_ALLOW_PRIVATE=true disables it (dev-only; logs a startup warning).
• HttpService trait (picloud-shared) + HttpServiceImpl (manager-core, reqwest-backed). Wired into the Services bundle as http: Arc<dyn HttpService>.
• Capability::AppHttpRequest(AppId) — maps to the existing script:write scope (any outbound request can exfiltrate data, so the conservative write mapping is used). No new Scope variant — the seven-scope commitment holds. Script-as-gate: skipped when the script runs unauthenticated.
• Cron triggers — POST /api/v1/admin/apps/{id}/triggers/cron (script_id, schedule, timezone, optional retry overrides). 6-field cron expressions (with seconds) validated by the cron crate; IANA timezones validated by chrono-tz. A scheduler task (spawn_cron_scheduler, poll cadence PICLOUD_CRON_TICK_INTERVAL_MS, default 30s) enqueues due triggers into the outbox; the existing dispatcher delivers them. Catch-up policy: a trigger that missed N windows fires exactly once on the next tick, not N times.
• ctx.event.cron — { schedule, timezone, scheduled_at, fired_at } for cron-trigger handlers (ctx.event.source == "cron", ctx.event.op == "tick").
• Dashboard Triggers tab — admin-gated cron trigger create form (target endpoint script, schedule, timezone dropdown) + triggers list showing schedule / timezone / last-fired.

Changed

• Workspace version: 1.1.3 → 1.1.4.
• Rhai SDK version: 1.4 → 1.5 (additive — http::* SDK + ctx.event.cron). The Services bundle constructor becomes Services::new(kv, docs, dead_letters, events, modules, http).
• Dashboard version: 0.9.0 → 0.10.0.
• SdkCallCx — gains a script_id field (audit attribution + the default outbound User-Agent, picloud/<version> (script:<id>)).
• Rhai pin tightened — workspace dep rhai = "1.19" → rhai = "=1.24" so future bumps of the non-semver-stable internals surface are deliberate.
• Module backend errors redacted — PicloudModuleResolver now surfaces a stable generic ("module backend unavailable; check server logs") to scripts and logs the original at error level, instead of leaking the backend error verbatim (see v1.1.3 follow-up).

Migrations

• 0017_cron_triggers.sql — widens triggers.kind and outbox.source_kind CHECK constraints to include 'cron'; adds cron_trigger_details (trigger_id, schedule, timezone, last_fired_at) with a last_fired_at index. Additive — applies cleanly on a fresh DB and on top of the v1.1.3 schema.

New environment variables

• PICLOUD_HTTP_ALLOW_PRIVATE (default false; dev-only) — disable the SSRF deny-list.
• PICLOUD_HTTP_MAX_REQUEST_BODY_BYTES / PICLOUD_HTTP_MAX_RESPONSE_BODY_BYTES (default 10 MB each).
• PICLOUD_CRON_TICK_INTERVAL_MS (default 30000) — cron scheduler poll cadence (floored at 1s).

v1.1.3 — Modules (unreleased)

Real per-app Rhai module system. Scripts can import "<name>" as <alias>; other scripts in the same app as reusable libraries. The v1.0 placeholder DummyModuleResolver is replaced by a per-call PicloudModuleResolver that loads kind = 'module' scripts via a new ModuleSource trait, compiles them into Rhai modules, caches the compiled output, and enforces cross-app isolation, circular- import detection, and an import-depth limit. Two LRU AST caches (top-level script + per-module compiled module) eliminate the per-invocation compile cost; both invalidate on updated_at change.

Added

• scripts.kind column — 'endpoint' | 'module', default 'endpoint'. Endpoints handle HTTP routes / trigger events; modules are libraries imported by other scripts. The dashboard scripts list + script detail page surface the distinction as a colored badge.
• script_imports dep-graph table — populated at script save- time from the literal-path import "<name>" declarations in the source. FK-CASCADE on both columns. No admin surface in v1.1.3 (drives a v1.2+ "Used by" dashboard panel and v1.3+ cluster-mode eager invalidation).
• ModuleSource trait — lookup(&SdkCallCx, name). Postgres impl PostgresModuleSource in manager-core. app_id derived from cx.app_id (cross-app isolation boundary, mirrors KV / docs).
• PicloudModuleResolver — implements rhai::ModuleResolver. Per-call instance owns Arc<SdkCallCx>, the in-progress imports stack, the depth counter. Bridges sync resolve() to async lookup() via Handle::block_on (safe under the executor's spawn_blocking wrap). Replaces DummyModuleResolver at line 139 of executor-core::engine::build_engine.
• Module-shape validation — kind = 'module' source must contain only fn declarations, const declarations, and import statements at top level (no executable expressions). Walks ast.statements() via rhai/internals. Admin endpoint is the primary gate; the resolver re-runs the check at load time for defense in depth against DB-direct inserts.
• Per-module compiled-Module cache — LruCache<(AppId, name), (updated_at, Arc<rhai::Module>)> owned by Engine. Invalidated lazily on updated_at mismatch. Size via PICLOUD_MODULE_CACHE_SIZE (default 512).
• Top-level script AST cache — LruCache<ScriptId, (updated_at, Arc<rhai::AST>)> owned by LocalExecutorClient. Same staleness semantics. Size via PICLOUD_SCRIPT_CACHE_SIZE (default 256).
• ScriptIdentity + ExecutorClient::execute_with_identity — new method on the trait; default impl forwards to execute so RemoteExecutorClient (and future transports) keep working. LocalExecutorClient overrides it to consult the script cache and pass the resulting Arc<rhai::AST> to Engine::execute_ast.
• Engine::execute_ast — companion to execute that takes a pre-compiled AST so callers (the orchestrator) can reuse one compile across many invocations.
• Import depth limit — Limits::module_import_depth_max (default 8). Not script-overridable.
• Reserved module names — module-kind scripts cannot be named log, regex, random, time, json, base64, hex, url, kv, docs, dead_letters, http, files, pubsub, secrets, email, users, queue. Defense against author confusion with stdlib namespaces.

Changed

• Workspace version: 1.1.2 → 1.1.3.
• Rhai SDK version: 1.3 → 1.4 (additive — every v1.3 script still runs unchanged; new surface: import "<name>" as <alias>; for endpoint scripts that consume modules in the same app).
• Dashboard version: 0.8.0 → 0.9.0. Adds kind dropdown on script create + kind badges on the scripts list and detail page.
• Services bundle — grows a modules: Arc<dyn ModuleSource> field. Constructor signature becomes Services::new(kv, docs, dead_letters, events, modules).
• ScriptValidator trait — validate now returns ValidatedScript { imports: Vec<String> } so the repo can write dep-graph edges in the same transaction as the script row. New validate_module method enforces module-shape rules.
• Trigger creation tightening — POST /api/v1/admin/apps/{id}/triggers/{kv,docs,dead_letter} now load the target script and reject when (1) it doesn't exist, (2) it belongs to a different app (latent v1.1.1/v1.1.2 gap — closed in v1.1.3), or (3) it is kind = 'module'.
• Route creation — POST /api/v1/admin/scripts/{id}/routes returns 400 when the target script is kind = 'module'.

Security fix

• Cross-app trigger target (CVE-class: broken access control). In v1.1.1 and v1.1.2, POST /api/v1/admin/apps/{id}/triggers/{kv,docs,dead_letter} validated only that the caller could manage triggers on {id} — it did not verify that the target script_id belonged to that same app. A member with trigger-management rights on app A could therefore register a trigger in A pointing at a script owned by app B, causing B's script to execute on A's events (a cross-app isolation break). v1.1.3 closes this: every trigger-create handler now loads the target script and rejects it unless script.app_id == path app_id (and it is not a module). Upgrade recommendation: anyone running a pre-v1.1.3 multi-tenant deploy should upgrade and audit existing triggers rows for any whose script_id resolves to a script in a different app_id.

Migrations

• 0015_scripts_kind.sql — adds scripts.kind with CHECK IN ('endpoint','module'), composite index (app_id, kind), and a module-name shape CHECK (^[a-zA-Z_][a-zA-Z0-9_]{0,63}$).
• 0016_script_imports.sql — adds the dep-graph table with FK CASCADE on both columns, PK (importer, imported), and a reverse-edge index on imported_script_id.

Downgrade caveats

Rolling back v1.1.3 → v1.1.2 with module-kind scripts present strands them (no kind column means everything looks like an endpoint; modules will then succeed as route targets and immediately fail to execute meaningfully). Migration 0016_script_imports.sql is safe to drop (the table is auxiliary). 0015_scripts_kind.sql must be reversed by DROP COLUMN kind only after manually re-homing or deleting module-kind rows.

v1.1.2 — Documents (unreleased)

docs::* SDK — schemaless JSONB document storage with a first-cut query DSL — plus docs:* triggers as the second concrete kind on the v1.1.1 triggers framework. Sets the precedent for the v1.2 query DSL expansion and dead_letters::list.

Added

• Docs store — docs table keyed (app_id, collection, id) with JSONB values and a GIN-on-jsonb_path_ops index. Rhai SDK exposes the handle pattern: docs::collection(name).{create,get,find,find_one,update,delete,list}. Cursor-style pagination on list. Cross-app isolation enforced via cx.app_id (never script-passed). Document envelope shape returned by reads: #{ id, data: #{...}, created_at, updated_at } — explicit metadata + user-data separation (sets precedent for v1.2 dead_letters::list).
• Query DSL (v1.1.2 subset) — implicit equality at top level (#{ tier: "gold" }), operator-object form (#{ created_at: #{ "$gt": "..." } }), dotted field paths up to 5 levels ("user.email"), and operators $eq/$ne/$gt/$gte/ $lt/$lte/$in. Filter modifiers $sort (single field) and $limit. Unsupported operators ($or, $regex, etc.) reject with a clear v1.2-pointer error.
• Docs triggers (docs:*) — docs_trigger_details table mirrors kv_trigger_details. Admin endpoint POST /api/v1/admin/apps/{id}/triggers/docs accepts the same DTO shape as the KV endpoint with ops of DocsEventOp (create / update / delete). Dispatcher routes OutboxSourceKind::Docs through the same generic path as KV + dead-letter.
• ctx.event.docs.prev_data — change-data-capture surface for docs trigger handlers. prev_data carries the document state prior to the mutation (None for create), letting handlers see what changed. The repo reads the old row in the same SQL statement as the write so the trigger event has the prior value.
• Capability::AppDocsRead(AppId) + AppDocsWrite(AppId) — granted to Viewer / Editor respectively in the per-app role table. Same trust shape as KV's AppKvRead / AppKvWrite.

Changed

• Workspace version: 1.1.1 → 1.1.2.
• Rhai SDK version: 1.2 → 1.3 (additive — every v1.2 script still runs unchanged; new surfaces: docs::collection(name).{...}, ctx.event.docs for triggered handlers).
• Dashboard version: 0.7.0 → 0.8.0. Workspace alignment; no docs-specific UI in v1.1.2 (the dashboard's Rhai-mode hints don't list KV completions either — focused UX pass is a separate task).
• Services bundle — grows a docs: Arc<dyn DocsService> field. Constructor signature becomes Services::new(kv, docs, dead_letters, events).
• Scope mapping: API keys with script:read scope can call docs::find / get / list; script:write can call docs::create / update / delete. Same trust shape as KV — honors the seven-scope commitment from v1.1.0.

Migrations

• 0013_docs.sql — docs table + per-(app_id, collection) index + GIN-on-jsonb_path_ops index.
• 0014_docs_triggers.sql — extends triggers.kind and outbox.source_kind CHECK constraints to include 'docs'; adds docs_trigger_details table.

Downgrade caveats

Rolling a deployment back from v1.1.2 → v1.1.1 with docs-source outbox rows still queued will cause the v1.1.1 dispatcher to fail deserialising TriggerEvent::Docs (#[serde(tag = "source")] rejects unknown variants). Drain or delete outbox WHERE source_kind = 'docs' before downgrading. Trunk-only deployments don't hit this.

Known limitations

• Text-lex comparison for $gt / $gte / $lt / $lte is incorrect for unpadded numbers crossing digit-count boundaries ('10' < '9' is TRUE under any text collation). Workaround: zero-pad numeric strings. v1.2's advanced query expansion adds numeric-aware operators.
• Concurrent update()s on the same doc may both emit the pre-update prev_data (last-writer-wins). Inherited from KV's set pattern; documented for forensic-trace use cases.
• v1.1.2 has no partial-update DSL — scripts that want partial update do get + modify + update. Planned for v1.2.

v1.1.1 — Storage & Events (unreleased)

The triggers framework — KV store + universal outbox + dispatcher + NATS-style sync HTTP + per-route async dispatch + dead-letter handling + dashboard surface. Every subsequent v1.1.x service module (docs, files, pubsub, …) hangs off the dispatcher built here.

Added

• KV store — kv_entries table keyed (app_id, collection, key) with JSONB values. Rhai SDK exposes the handle pattern: kv::collection(name).{get,set,has,delete,list}. Cursor-style pagination with opaque base64 cursors. Cross-app isolation enforced via cx.app_id (never script-passed).
• Triggers framework (Layout E) — parent triggers table + per-kind detail tables (kv_trigger_details, dead_letter_trigger_details). Trigger CRUD admin endpoints (/api/v1/admin/apps/{id}/triggers/{kv,dead_letter}) + Capability::AppManageTriggers(AppId).
• Universal outbox + dispatcher — single tokio task that polls the outbox via FOR UPDATE SKIP LOCKED, routes due rows to the executor through the shared ExecutionGate. Retry with exponential backoff + ±jitter; on exhaustion, dead-letter.
• NATS-style sync HTTP via outbox — InboxRegistry (in-process oneshot map) lets the orchestrator await dispatcher delivery on every sync HTTP request. Cluster mode (v1.3+) swaps this for LISTEN/NOTIFY behind the same InboxResolver trait.
• dispatch_mode: async on routes — POST to a route with dispatch_mode = 'async' returns 202 Accepted immediately; the script runs via the dispatcher (with retries / dead-letter).
• Dead-letter handling — separate dead_letters table per design notes §4. dead_letters::{replay,resolve} Rhai SDK + admin endpoints + Capability::AppDeadLetterManage(AppId). Recursion-stop rule: dead-letter handler failures annotate the original row as resolution = 'handler_failed' and never produce a new dead-letter or retry.
• Dashboard surface for dead letters — unresolved-count red badge on the apps list + per-app page; per-app dead-letters list view at /admin/apps/{slug}/dead-letters with Replay + Mark resolved per-row actions and expandable payload detail.
• abandoned_executions table — forensic row written by the dispatcher when it tries to resolve an inbox the orchestrator already abandoned (timed out). Counter metric path reserved.
• Trigger-depth limit — cx.trigger_depth > max_trigger_depth (default 8) skips execution + logs; does NOT dead-letter (depth-exceeded means "you built a loop").
• GC sweepers — weekly retention sweeps for dead_letters (30 days) and abandoned_executions (7 days), both with FOR UPDATE SKIP LOCKED for cluster-mode safety.
• Env-overridable trigger config — TriggerConfig::from_env reads PICLOUD_MAX_TRIGGER_DEPTH, PICLOUD_TRIGGER_RETRY_*, PICLOUD_DEAD_LETTER_RETENTION_DAYS, PICLOUD_ABANDONED_EXECUTIONS_RETENTION_DAYS.

Changed

• Workspace version: 1.1.0 → 1.1.1.
• Rhai SDK version: 1.1 → 1.2 (additive — every v1.1 script still runs unchanged; new surfaces: kv::*, dead_letters::*, ctx.event for triggered handlers).
• Dashboard version: 0.6.0 → 0.7.0 for the dead-letters UI.
• Services bundle — replaces v1.1.0's no-arg Services::new() with explicit Services::new(kv, dead_letters, events). Tests use Services::default() for an all-noop bundle.
• SdkCallCx grows is_dead_letter_handler: bool and event: Option<TriggerEvent> fields.
• ExecRequest mirrors the new SdkCallCx fields and grows event for serializable trigger payload transport.
• Routes table grows dispatch_mode TEXT NOT NULL DEFAULT 'sync' (CHECK in {sync, async}).
• Schema version: 6 → 12 (migrations 0007 through 0012).

Migrations

• 0007_kv.sql — kv_entries table + index
• 0008_triggers.sql — triggers + kv_trigger_details + dead_letter_trigger_details
• 0009_outbox.sql — universal outbox table + due-row partial index
• 0010_dead_letters.sql — dead_letters table + unresolved partial index + GC index
• 0011_abandoned_executions.sql — forensic table + GC index
• 0012_routes_dispatch_mode.sql — routes.dispatch_mode column

v1.1.0 — Foundation & Standard Library

See docs/v1.1.x-design-notes.md §7 for the full v1.1.x roadmap.