chore(release): bump workspace to v1.1.2 + CHANGELOG

Workspace package version 1.1.1 -> 1.1.2; dashboard 0.7.0 -> 0.8.0
(workspace alignment, no docs-specific UI yet); SDK_VERSION
1.2 -> 1.3 for the docs:: surface + ctx.event.docs additions.

CHANGELOG entry documents the docs store, the query DSL subset, the
docs:* trigger kind, the prev_data change-data-capture surface, and
the new AppDocsRead/AppDocsWrite capabilities. Includes a downgrade
caveat (v1.1.2 -> v1.1.1 with queued docs outbox rows would fail
TriggerEvent deserialization) and known-limitations notes for the
text-lex comparison gotcha and the concurrent-update prev_data race.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-02 19:56:00 +02:00
parent 2a047f1f85
commit 277ba34e21
4 changed files with 98 additions and 11 deletions

View File

@@ -1,5 +1,92 @@
# PiCloud Changelog
## 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 +