@colixsystems/widget-sdk 0.17.0 → 0.19.0

package/README.md

@@ -1,23 +1,87 @@
 # @colixsystems/widget-sdk
 
-Common widget interface for [AppStudio](https://github.com/appstudio). This package implements the contract that every widget — built-in or third-party, web or native — speaks: a `WidgetManifest`, a `WidgetContext`, a property schema, the helper hooks, and the static linter that gates submissions.
+Common widget interface for [AppStudio](https://github.com/appstudio). This package is **core only** — it implements the contract that every widget (built-in or third-party, web or native) speaks: a `WidgetManifest`, a `WidgetContext`, a property schema, the primitives + rendering surface, the helper hooks, events, theme/i18n, and the static linter that gates submissions. **It owns no HTTP and depends on none of the data SDK packages.**
+
+The data layer lives in **four separate domain-client packages**, each instantiated by the host and **injected into `WidgetContext`**. Widgets never import those packages — they reach the data surface only through this SDK's hooks, which read the injected client instances:
+
+| Injected at | Package | Surface (snake_case verbatim, `list` → `{ data, meta }`) |
+| ----------- | ------- | -------- |
+| `ctx.datastore` | `@colixsystems/datastore-client` | `tables.{list,get}`, `schema(tableId)`, `records(tableId).{ list(query), get(id), create(values), update(id,values) [PATCH], delete(id), aggregate(spec), permissions(recordId).{ list, grant, update, revoke } }` |
+| `ctx.directory` | `@colixsystems/directory-client` | `me()`, `users.{list,get,invite,deactivate,reactivate}`, `groups.{list,create,remove,addMember,removeMember,listMine}`, `invites.{list,revoke,resend}` |
+| `ctx.files` | `@colixsystems/files-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useFile()` resolves |
+| `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
+
+**Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no client-side case transform anywhere** — the only transform left in the system is the backend's wire ↔ Prisma middleware. Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
+
+**Hooks read the injected clients** — they do not hold their own HTTP. This is the **complete** hook surface (18 hooks), grouped by the domain client each one reads. **CORE** hooks read host state directly off `WidgetContext` (no data client); the rest delegate to one of the four injected clients. The grouping mirrors the banner sections in [`src/hooks.js`](src/hooks.js).
+
+| Group | Hook (signature) | Returns | Reads / scope |
+| ----- | ---------------- | ------- | ------------- |
+| **CORE** | `useTheme()` | `{ colors, spacing, radii, typography }` | `ctx.workspace.theme` — no scope |
+| **CORE** | `useUser()` | `{ id, email, display_name, roles, group_ids }` | `ctx.user` (snake_case verbatim; `id` null when anonymous) — no scope |
+| **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
+| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
+| **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
+| **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
+| **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
+| **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope |
+| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
+| **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
+| **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
+| **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
+| **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
+| **FILES** (`ctx.files`) | `useFile(id)` | `{ url, file, loading, error, refetch }` | `ctx.files.get` — no scope |
+| **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
+| **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (mutations also `users.write:*`) |
+| **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
+| **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
+
+All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
+
+`ctx.recordPermissions`, `ctx.users`, and `ctx.groups` **no longer exist** — they were folded into `ctx.datastore.records(t).permissions` and `ctx.directory.{users,groups}` respectively.
 
 See the design reference for the full architecture: [`docs/architecture/widget-marketplace.md`](../../docs/architecture/widget-marketplace.md), specifically section 3.1.
 
 ## Status
 
-`v0.17.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.19.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
-### What's new in 0.17.0
+### What's new in 0.19.0
 
-REQ-WBLT-FORMBUILDER — a runtime schema resolver so widgets can render by column type.
+**The data layer splits into four injected domain clients; the SDK becomes core-only.**
 
-- **`useDatastoreSchema(tableId)` is wired** + the new `WidgetContext.datastore.schema` slice. Returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (`null` until loaded). It reads the **existing** ACL-gated `GET /api/v1/tables/:id` — structure only, never row data — so a public-grant table resolves for anonymous visitors exactly like a record read. Use it to resolve a stored `columnId` to its column name / dataType / relation target at runtime (the built-in Form Builder uses it to render an input per column type). Reads need the `datastore.read:<table>` scope. Backed by a new `datastore.schema(tableId)` host facade (web: `widgetHostDatastore`; native: `hostDatastore` in the export's `widgetHost.js`). Additive.
+- **The SDK no longer owns any data facade.** The bespoke per-hook facades that used to live on `WidgetContext` (`ctx.datastore` as an opaque host object, `ctx.directory.listUsers`, `ctx.users`, `ctx.groups`, `ctx.recordPermissions`, `ctx.files.get`) are replaced by four host-instantiated, host-injected domain clients: `ctx.datastore` (`@colixsystems/datastore-client`), `ctx.directory` (`@colixsystems/directory-client`), `ctx.files` (`@colixsystems/files-client`, flattened), `ctx.payments` (`@colixsystems/payments-client`). The SDK imports none of them and ships no HTTP.
+- **`ctx.recordPermissions`, `ctx.users`, `ctx.groups` are removed.** Per-record permission management moved under `ctx.datastore.records(tableId).permissions(recordId)`; user / group administration moved under `ctx.directory.users` / `ctx.directory.groups`. The hooks (`useRecordPermissions`, `useUsers`, `useGroups`) keep the same names and signatures — only the client slice they read changed.
+- **snake_case end to end, no client-side transform.** Clients send and return snake_case verbatim (`group_ids`, `can_read`, `is_active`, `amount_cents`, `data_type`, `created_at`, …). The SDK passes bodies straight through and unwraps the `{ data, meta }` list envelope without renaming a single field. Hook return rows and `useUser()` fields are therefore snake_case (`display_name`, `group_ids`, `is_active`, `member_count`, and `useRecordPermissions` rows carry `user_id` / `group_id` / `can_read` / `can_write` / `can_delete` / `can_grant`).
+- **Companion package versions:** `datastore-client 0.5.0`, `files-client 0.3.0`, `directory-client 0.1.0`, `payments-client 0.1.0`.
+- **`CONTRACT.version` → `1.9.0`.** Breaking for `WidgetContext` consumers (removed slices, renamed wire fields); the hook export surface is unchanged.
+
+### What was in 0.18.0
+
+Two additive features land in this version.
+
+**A widget may declare server-side actions in its manifest.**
+
+- **`WidgetManifest.actions` is now part of the public contract.** An optional array; each entry is `{ key, name, description?, triggerType, scheduleCron?, timeoutMs?, scriptSource }`. `triggerType` is one of `schedule`, `record_created`, `record_updated`, `record_deleted`; `scheduleCron` is required when `triggerType === "schedule"`. The `scriptSource` (≤ 200 KiB) runs in the **shared isolated-vm action runner** — against `datastore` / `fetch` / `console` / `record` / `tenantId` (the runner surface, **not** the React/SDK widget surface, so SDK imports and hooks are unavailable there and the component linter does not scan it). Actions never run in the rendered app, so they have **no effect on Player ↔ export parity**.
+- **Operators enable actions per tenant** from the Properties Panel. An enabled action materialises a tenant `Action` row **DISABLED** until the operator binds an integration API key (and, for `record_*` triggers, a target table) in the Actions admin page — those bindings are tenant-local, so `triggerTableId` / `apiKeyId` must **not** appear in the manifest (the validator and linter reject them).
+- **New contract fields** `CONTRACT.actionTriggerTypes`, `CONTRACT.actionScriptGlobals`, `CONTRACT.actionScriptMaxBytes` expose the grammar so the Developer page, the AI agent prompt, and `validateManifest` derive it from one source. `validateManifest` now structurally validates `actions`; the marketplace linter rejects malformed / oversized declarations.
+- **New manifest category `ADMINISTRATION`** for app-administration widgets such as User Management. Added to `CONTRACT.manifestCategories`, `validateManifest`, the `WidgetCategory` type, the marketplace category list, and the master-DB `WidgetCategory` enum.
+
+**Per-record permission management from inside a widget.**
+
+- **`useRecordPermissions(tableId, recordId)` is wired** + the new `WidgetContext.recordPermissions` slice + the new `acl.write:records` scope. Returns `{ permissions, loading, error, grant, revoke, update, refetch }` where `permissions` is `Array<{ id, principalType: "USER" | "GROUP" | "PUBLIC", principalId, canRead, canWrite, canDelete, canGrant }>`. Rejections from `grant` / `revoke` / `update` surface as a structured `PermissionError` (named export) with `code` ∈ `FORBIDDEN | VALIDATION | NOT_FOUND | CONFLICT | INTERNAL`. When `tableId` or `recordId` is null/empty the hook collapses to a stable empty no-op result. Mutating requires `acl.write:records` AND `canGrant` on the target record — Studio owners pass automatically; an APP_USER holds `canGrant` as the record's creator or via a delegated grant. Backs the built-in Chat widget's "+ New channel" + DM-create flows. Additive.
+- **`CONTRACT.version` → `1.8.0`** (additive: a new optional `actions` manifest field, three new contract fields, the `ADMINISTRATION` category, the `useRecordPermissions` hook, the `recordPermissions` context slice, the `acl.write:records` scope, and the `PermissionError` class). No existing export changed signature.
+
+### What was in 0.17.0
+
+A runtime schema resolver so widgets can render by column type.
+
+- **`useDatastoreSchema(tableId)` is wired** + the new `WidgetContext.datastore.schema` slice. Returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (`null` until loaded). Reads structure only, never row data, so a public-grant table resolves for anonymous visitors like a record read. Use it to resolve a stored `columnId` to its name / dataType / relation target at runtime. Reads need the `datastore.read:<table>` scope. Additive.
 - **`CONTRACT.version` → `1.7.0`** (additive: one new hook, one new `datastore.schema` context field). No existing export changed signature.
 
 ### What's new in 0.16.0
 
-REQ-THEME — the tenant's **Theme Settings** now flow all the way into `useTheme()`.
+The tenant's **Theme Settings** now flow all the way into `useTheme()`.
 
 - **`themeTokens.colors` gains `secondary` + `onSecondary`.** `useTheme().colors.secondary` reflects the tenant's *Secondary Color* picker (with `onSecondary` as its readable contrast color), alongside the existing `primary` / `onPrimary`. Built-in widgets like Button use it for their secondary variant; third-party widgets can use it for a branded second accent. The full `colors` shape is now `{ primary, onPrimary, secondary, onSecondary, surface, onSurface, surfaceMuted, onSurfaceMuted, border, danger, success, warning, info }`.
 - **`colors.primary` / `colors.secondary` / `typography.fontFamily` are tenant-resolved.** The host maps the Studio Theme Settings blob (Primary Color, Secondary Color, Global Font) onto the default tokens before handing them to `useTheme()`, on both the live Player and the exported app — so a widget that reads tokens re-themes automatically. (Custom Google fonts render in the Player today; the exported app falls back to the system face for non-system fonts until font bundling lands.)
@@ -25,7 +89,7 @@ REQ-THEME — the tenant's **Theme Settings** now flow all the way into `useThem
 
 ### What's new in 0.15.0
 
-REQ-WSDK-PLATFORM — the "split-implementation + vetted package list" pivot. See [`docs/design/req-widget-sdk-cross-platform-primitives.md`](../../docs/design/req-widget-sdk-cross-platform-primitives.md) for the full design and rationale.
+The "split-implementation + vetted package list" pivot.
 
 - **`CONTRACT.vettedImports` (new).** A curated allowlist of bare specifiers a widget may import — `react`, `@colixsystems/widget-sdk`, `react-native`, `axios`, `date-fns`, `react-native-svg`, `lucide-react-native`, `react-native-maps`, `leaflet`, `react-leaflet`, `expo-av`, `@react-native-community/datetimepicker`, `expo-clipboard`, `expo-haptics`. Each entry carries `platforms` (one or both of `"web"` / `"native"`) and a `category` so the linter and the marketplace listing can render honest platform badges. `CONTRACT.allowedBareImports` (the existing field) is now derived from `vettedImports` and stays a plain `string[]` for back-compat.
 - **`fetch` and `XMLHttpRequest` come off `CONTRACT.bannedApis`.** Widgets may call third-party APIs directly. Calls to the host's own `/api/*` surface will 401 because the JWT token is never shared with widget code; the linter emits a soft `no-host-api-url` warning when it sees host-URL substrings so authors learn the rule statically. Use SDK hooks (`useDatastoreQuery`, `useUsers`, `useFile`, …) for workspace data; use `axios` / `fetch` for third-party APIs.
@@ -41,12 +105,12 @@ REQ-WSDK-PLATFORM — the "split-implementation + vetted package list" pivot. Se
 
 ### What was in 0.14.1
 
-- **`groupRef` property type (REQ-USERMGMT M4 / §4.8).** Authors can now declare `{ type: 'groupRef', label: 'Group' }` in their `propertySchema` to render a Group picker in the Studio Properties Panel. The widget receives a bare `AppUserGroup` UUID — REQ-GEN-07 compliant, so tenant-copy walks the value transparently. Used by the built-in `appstudio.user-management` widget for its `defaultGroupId` prop and available to third-party widgets that need to anchor behaviour on a specific group.
+- **`groupRef` property type.** Authors can declare `{ type: 'groupRef', label: 'Group' }` in their `propertySchema` to render a Group picker in the Studio Properties Panel. The widget receives a bare `AppUserGroup` UUID, so tenant-copy walks the value transparently. Used by the built-in `appstudio.user-management` widget for its `defaultGroupId` prop and available to third-party widgets that need to anchor behaviour on a specific group.
 - **Patch bump** — additive enumeration entry, no exported function signature changed. `CONTRACT.version` stays `1.4.0`.
 
 ### What's new in 0.14.0
 
-- **`useUsers()` + `useGroups()` — AppUser administration hooks (REQ-USERMGMT / REQ-ACL-SYS M3).** A widget can now invite, deactivate, reactivate, and remove members, and create / delete groups + add / remove members, from a published-app surface. Returns `{ users | groups, loading, error, refetch, ... }` plus imperative mutation methods. Reads gated by `users.read:*` / `groups.read:*`; mutations by `users.write:*` / `groups.write:*`. Rejections surface as a structured `DirectoryError` (new named export) with `code` ∈ `FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY`. The host signs an `X-Widget-Scopes` header against `JWT_SECRET` so an APP_USER cannot forge a scope set, and the backend additionally gates the request behind a SystemAcl `users.*` / `groups.*` capability grant (REQ-ACL-SYS M1 + M3).
+- **`useUsers()` + `useGroups()` — AppUser administration hooks.** A widget can invite, deactivate, reactivate, and remove members, and create / delete groups + add / remove members, from a published-app surface. Returns `{ users | groups, loading, error, refetch, ... }` plus imperative mutation methods. Reads gated by `users.read:*` / `groups.read:*`; mutations by `users.write:*` / `groups.write:*`. Rejections surface as a structured `DirectoryError` (new named export) with `code` ∈ `FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY`. The host signs an `X-Widget-Scopes` header against `JWT_SECRET` so an APP_USER cannot forge a scope set, and the backend additionally gates the request behind a SystemAcl `users.*` / `groups.*` capability grant.
 - **Managing app users from a widget — see the section below.**
 - **New linter rule `no-scope-mismatch-useUsers` / `no-scope-mismatch-useGroups`.** Calling `useUsers().invite()` / `.deactivate()` / `.reactivate()` / `.remove()` without `users.write:*` in the manifest's `requestedScopes` fails the lint; calling `useGroups()` mutation methods without `groups.write:*` fails the lint. Keeps the manifest honest at submission time.
 - **`CONTRACT.version` → `1.4.0`** (additive: two new hooks, two new context slices, six new scope verbs, one new error class). No existing export changed signature.
@@ -71,12 +135,12 @@ REQ-WSDK-PLATFORM — the "split-implementation + vetted package list" pivot. Se
 
 ### What's new in 0.9.0
 
-- **`usePayments()` — incoming app-user payments (REQ-BILL-07-WIDGETPAY).** Returns `{ requestPayment, getPayment }`. `requestPayment({ amountCents, currency?, description, metadata?, returnPath? })` triggers a one-time charge from the signed-in app user and resolves to `{ id, status, checkoutUrl? }`: when `checkoutUrl` is present the widget opens it (web: navigate; native: `expo-web-browser`) — the user pays in **hosted Stripe Checkout**; when absent (the platform's built-in **mock** provider, the default until Stripe is configured) the charge auto-confirms (`status: "PAID"`). `getPayment(id)` polls the terminal status. Backed by a new `WidgetContext.payments` slice and gated by the new `payments.charge:appUser` scope. **No card data ever touches the widget** — never collect card fields yourself. The charge settles to the workspace owner; the amount is bounded by a platform per-charge cap. Rejections are a structured `PaymentError` (also a new named export) with a stable `.code`.
+- **`usePayments()` — incoming app-user payments.** Returns `{ requestPayment, getPayment }`. `requestPayment({ amountCents, currency?, description, metadata?, returnPath? })` triggers a one-time charge from the signed-in app user and resolves to `{ id, status, checkoutUrl? }`: when `checkoutUrl` is present the widget opens it (web: navigate; native: `expo-web-browser`) — the user pays in **hosted Stripe Checkout**; when absent (the platform's built-in **mock** provider, the default until Stripe is configured) the charge auto-confirms (`status: "PAID"`). `getPayment(id)` polls the terminal status. Backed by a new `WidgetContext.payments` slice and gated by the new `payments.charge:appUser` scope. **No card data ever touches the widget** — never collect card fields yourself. The charge settles to the workspace owner; the amount is bounded by a platform per-charge cap. Rejections are a structured `PaymentError` (also a new named export) with a stable `.code`.
 - **`CONTRACT.version` → `1.2.0`** (additive: one new hook, one new context slice, one new scope, one new error class). No existing export changed signature.
 
 ### What was in 0.8.0
 
-- **`useDirectory()` — read-only user directory hook (REQ-DIR-01).** Returns `{ users, loading, error, refetch }` where each user is `{ id, name, role }`. Backed by a new `WidgetContext.directory.listUsers(query)` slice and gated by the new `directory.read:users` scope. Use it to build a chat people-list, an @-mention picker, or to resolve an author id to a display name. The host reads `GET /api/v1/app/users`, which hands non-Studio (Player) callers the reduced `{ id, name, role }` projection — email and other admin-only fields never leave the server for an app end-user. `query` is an optional `{ q, role, isActive, limit, offset }` (`q` substring-matches the display name; `role` is `"USER"` (default), `"INTEGRATION"`, or `"ALL"`). Mutating users is not part of the widget surface — the directory is read-only.
+- **`useDirectory()` — read-only user directory hook.** Returns `{ users, loading, error, refetch }` where each user is `{ id, name, role }`. Gated by the new `directory.read:users` scope. Use it for a chat people-list, an @-mention picker, or to resolve an author id to a display name. Player callers get the reduced `{ id, name, role }` projection — email and other admin fields never leave the server for an app end-user. `query` is an optional `{ q, role, isActive, limit, offset }` (`q` substring-matches the display name; `role` is `"USER"` (default), `"INTEGRATION"`, or `"ALL"`). The directory is read-only.
 - **`CONTRACT.version` → `1.1.0`** (additive: one new hook, one new context slice, one new scope). No existing export changed signature.
 
 ### What was in 0.7.0
@@ -95,7 +159,7 @@ REQ-WSDK-PLATFORM — the "split-implementation + vetted package list" pivot. Se
 ### What was in 0.5.0
 
 - **`TextInput` primitive.** Cross-platform controlled text field — web maps to `<input type="text">` (or `<textarea>` when `multiline` is true), native maps to `react-native` `TextInput`. Props: `value`, `onChangeText`, `placeholder`, `multiline`, `rows`, `disabled`, `style`. Fixes the gap that forced widgets to fall back to raw `<textarea>` (web-only). The AI Widget Agent's system prompt now documents this primitive.
-- **`useDatastoreMutation(...).update(id, partial)` is wired.** Hits `PATCH /api/v1/tables/:tableId/records/:id`, which now exists on the backend (REQ-DML-PATCH). Partial-update semantics — only the supplied columns are mutated, the rest of the row is left intact. MANY_TO_MANY relations follow replace-set semantics when supplied; omitting the column leaves the existing links alone. Constraint enforcement (REQ-CONS-04) runs against the merged row, excluding self so a re-affirm doesn't trip its own UNIQUE.
+- **`useDatastoreMutation(...).update(id, partial)` is wired.** Partial-update semantics — only the supplied columns are mutated, the rest of the row is left intact. MANY_TO_MANY relations follow replace-set semantics when supplied; omitting the column leaves the existing links alone. Constraint enforcement runs against the merged row, excluding self so a re-affirm doesn't trip its own UNIQUE.
 
 ### What was in 0.4.1
 
@@ -122,7 +186,7 @@ REQ-WSDK-PLATFORM — the "split-implementation + vetted package list" pivot. Se
 
 ### What was in 0.3.0
 
-Additive: `WidgetManifest` carries an optional `datastoreTemplate` field. When a tenant installs a widget that declares one, the table set is seeded into their workspace alongside the install. Tables follow the existing built-in template semantics (auto-suffixed naming, REQ-ACL-05 creator-grants, REQ-TEMPLATES-ACL public grants, REQ-ACL-RELINHERIT cross-relation inheritance) and persist when the widget is later uninstalled. See `WidgetDatastoreTemplate` in `src/index.d.ts` for the structural constraints — at most 8 tables per widget, 24 columns per table, RELATION columns address siblings by `suffix`.
+Additive: `WidgetManifest` carries an optional `datastoreTemplate` field. When a tenant installs a widget that declares one, the table set is seeded into their workspace alongside the install. Tables follow the built-in template semantics (auto-suffixed naming, creator-grants, public grants, cross-relation inheritance) and persist when the widget is later uninstalled. See `WidgetDatastoreTemplate` in `src/index.d.ts` for the constraints — at most 8 tables per widget, 24 columns per table, RELATION columns address siblings by `suffix`.
 
 ## Public API
 
@@ -132,14 +196,14 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (`id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, dataType, required, relationType, targetTableId, isIdentification }] }` (structure only, no row data) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useFile`, `useWidgetEvent`, `usePayments`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useUser()` returns the active end-user identity `{ id, email, display_name, roles, group_ids }` (snake_case verbatim; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useFile(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`, `DateTimePicker` wraps `@react-native-community/datetimepicker`). The web build aliases `react-native` to `react-native-web` so widgets render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
 ## Managing app users from a widget
 
-REQ-USERMGMT / REQ-ACL-SYS M3 added two hooks that let a widget invite, deactivate, reactivate, and remove members, plus create / delete groups and add / remove their members. The hooks are gated by two layers: the widget's manifest must declare the scope (so the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability in the tenant (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller does not hold the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that to the end-user as a "you do not have permission to do that" message.
+`useUsers()` and `useGroups()` let a widget invite, deactivate, reactivate, and remove members, plus create / delete groups and add / remove their members. Two gates apply: the manifest must declare the scope (the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller lacks the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that as a "you do not have permission" message.
 
 ```js
 import { Text, View, Pressable, useUsers, useGroups } from "@colixsystems/widget-sdk";
@@ -152,7 +216,7 @@ export default function MemberManager() {
     <View>
       {users.map((u) => (
         <View key={u.id}>
-          <Text>{u.name} — {u.isActive ? "active" : "inactive"}</Text>
+          <Text>{u.name} — {u.is_active ? "active" : "inactive"}</Text>
           <Pressable onPress={() => deactivate(u.id)}><Text>Deactivate</Text></Pressable>
           <Pressable onPress={() => remove(u.id)}><Text>Remove</Text></Pressable>
         </View>
@@ -160,7 +224,7 @@ export default function MemberManager() {
       <Pressable
         onPress={async () => {
           try {
-            await invite({ email: "a@b.com", name: "New User", groupIds: [groups[0]?.id].filter(Boolean) });
+            await invite({ email: "a@b.com", name: "New User", group_ids: [groups[0]?.id].filter(Boolean) });
           } catch (err) {
             // err.code is one of FORBIDDEN | VALIDATION | NOT_FOUND | INVITE_ONLY
           }
@@ -184,6 +248,60 @@ The matching manifest declares the scopes:
 
 The host rejects calls whose scope is not declared in the manifest (the SDK linter catches this statically too). Declaring a write scope is also a consent prompt the Studio admin sees at install time — the wider the scope set, the more careful the admin is about granting the install.
 
+## Managing per-record permissions from a widget
+
+`useRecordPermissions(tableId, recordId)` is the in-app surface for sharing a single record with another user or group. The chat widget uses it to invite members into a channel — the channel record's per-record grants ARE the membership list (messages inherit those grants). The hook also covers project-workspace, document-sharing, and team-roster widgets that grant access record-by-record.
+
+The rows and bodies are snake_case verbatim. A row carries `user_id` OR `group_id` (both null = a public grant) plus the `can_read` / `can_write` / `can_delete` / `can_grant` flags; the hook reads `ctx.datastore.records(tableId).permissions(recordId)`.
+
+```js
+import { Text, View, Pressable, useRecordPermissions, PermissionError } from "@colixsystems/widget-sdk";
+
+export default function ShareRecord({ tableId, recordId, partnerUserId }) {
+  const { permissions, loading, grant, revoke } = useRecordPermissions(tableId, recordId);
+  if (loading) return <Text>Loading members…</Text>;
+  return (
+    <View>
+      {permissions.map((p) => (
+        <View key={p.id}>
+          <Text>{p.user_id || p.group_id || "public"} — {p.can_write ? "writer" : "reader"}</Text>
+          <Pressable onPress={() => revoke(p.id)}><Text>Remove</Text></Pressable>
+        </View>
+      ))}
+      <Pressable
+        onPress={async () => {
+          try {
+            await grant({
+              user_id: partnerUserId,
+              can_read: true,
+              can_write: true,
+              can_grant: true,
+            });
+          } catch (err) {
+            if (err instanceof PermissionError && err.code === "FORBIDDEN") {
+              // The signed-in user lacks can_grant on this record.
+            }
+          }
+        }}
+      >
+        <Text>Invite partner</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+The manifest declares the matching scope:
+
+```js
+{
+  // ...
+  requestedScopes: ["acl.write:records"],
+}
+```
+
+The server-side gate is `canGrant` on the target record — Studio owners pass automatically; an APP_USER holds `canGrant` as the record's creator or via a delegated grant. A caller without `canGrant` receives `PermissionError { code: "FORBIDDEN" }`. The hook collapses to a stable no-op when `tableId` or `recordId` is null/empty — so a widget can render its picker first, then bind to the picked record without conditional hook tricks.
+
 ## Linter
 
 ```sh

package/dist/contract.cjs

@@ -167,12 +167,12 @@ const HOOKS = [
     name: "useDirectory",
     signature: "useDirectory(query?)",
     returnShape: {
-      users: "Array<{ id, name, role }>",
+      users: "Array<{ id, name, role }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
-    requiredContextSlice: ["directory.listUsers"],
+    requiredContextSlice: ["directory.users"],
     scopes: ["directory.read:users"],
   },
   {
@@ -206,28 +206,26 @@ const HOOKS = [
     name: "useUsers",
     signature: "useUsers(query?)",
     description:
-      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
-      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
-      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
-      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+      "AppUser administration via the injected directory-client at " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate}. Returns " +
+      "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
+      "list returns the { data, meta } envelope verbatim — the hook unwraps " +
+      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "scope; mutations need users.write:*. The `invite` call accepts " +
+      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
+      "(the email is sent by the host).",
     returnShape: {
-      users: "Array<{ id, name, email?, role, isActive }>",
+      users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
     },
-    requiredContextSlice: [
-      "users.listUsers",
-      "users.invite",
-      "users.deactivate",
-      "users.reactivate",
-      "users.remove",
-    ],
+    requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
@@ -239,11 +237,14 @@ const HOOKS = [
     name: "useGroups",
     signature: "useGroups(query?)",
     description:
-      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
-      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "AppUserGroup administration via the injected directory-client at " +
+      "ctx.directory.groups.{list,create,remove,addMember,removeMember,listMine}. " +
+      "Returns { groups, loading, error, refetch, create, remove, addMember, " +
+      "removeMember }. list returns the { data, meta } envelope verbatim — the " +
+      "hook unwraps res.data; rows are snake_case. Reads need groups.read:*; " +
       "mutations need groups.write:*.",
     returnShape: {
-      groups: "Array<{ id, name, memberCount }>",
+      groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
@@ -255,15 +256,44 @@ const HOOKS = [
       removeMember:
         "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
     },
-    requiredContextSlice: [
-      "groups.listGroups",
-      "groups.create",
-      "groups.remove",
-      "groups.addMember",
-      "groups.removeMember",
-    ],
+    requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
+  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
+  // management for a single record. Mirror of contract.js.
+  {
+    name: "useRecordPermissions",
+    signature: "useRecordPermissions(tableId, recordId)",
+    description:
+      "Manage per-record VirtualPermission grants on a single record via the " +
+      "injected datastore-client at " +
+      "ctx.datastore.records(tableId).permissions(recordId).{list,grant,update,revoke}. " +
+      "Returns { permissions, loading, error, grant, revoke, update, refetch } " +
+      "where permissions is Array<{ id, user_id, group_id, can_read, can_write, " +
+      "can_delete, can_grant }> (snake_case rows verbatim; list() returns the " +
+      "{ data, meta } envelope and the hook unwraps res.data). grant/update " +
+      "bodies are snake_case verbatim ({ user_id | group_id, can_read, " +
+      "can_write, can_delete, can_grant }). Mutating requires acl.write:records " +
+      "scope AND can_grant on the target record (REQ-ACL-RELINHERIT-05: " +
+      "APP_USER actors with can_grant are accepted, not only Studio owners). " +
+      "When tableId or recordId is null/empty the hook collapses to an empty " +
+      "no-op result without a network round-trip.",
+    returnShape: {
+      permissions:
+        "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
+      loading: "boolean",
+      error: "PermissionError | null",
+      grant:
+        "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      revoke:
+        "(permissionId) => Promise<void>  // rejects with PermissionError",
+      update:
+        "(permissionId, { can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["acl.write:records"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -419,10 +449,40 @@ const CATEGORIES = [
   "DATA",
   "MEDIA",
   "COMMUNICATION",
+  // REQ-USERMGMT-06: app-administration widgets (User Management, …) the
+  // published app embeds for its own member management — its own palette
+  // section, distinct from COMMUNICATION.
+  "ADMINISTRATION",
   "CUSTOM",
 ];
 const PLATFORMS = ["web", "native"];
 
+// REQ-WIDGET-ACTION — server-side actions a widget may declare in its
+// manifest. Each runs in the shared isolated-vm action runner (see backend
+// action-runner.service.js) on a cron schedule or in response to a record
+// CRUD event — NEVER in the rendered app, so they never affect Player ↔
+// export parity. The trigger vocabulary mirrors the backend Action model.
+const ACTION_TRIGGER_TYPES = [
+  "schedule",
+  "record_created",
+  "record_updated",
+  "record_deleted",
+];
+// Globals the action script runs against (the runner's surface) — distinct
+// from the React/SDK widget surface, so the component import/banned-API
+// linter does NOT scan action scripts.
+const ACTION_SCRIPT_GLOBALS = [
+  "datastore",
+  "fetch",
+  "console",
+  "record",
+  "tenantId",
+  "triggerType",
+  "triggerTableId",
+];
+// Mirrors action.service.js SCRIPT_MAX_BYTES.
+const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -508,6 +568,17 @@ const MANIFEST_SCHEMA = {
     description:
       "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls.",
   },
+  actions: {
+    type: "object[]",
+    required: false,
+    description:
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      ACTION_TRIGGER_TYPES.join(", ") +
+      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      ACTION_SCRIPT_GLOBALS.join(", ") +
+      " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
+    default: [],
+  },
 };
 
 const WIDGET_CONTEXT_SHAPE = {
@@ -524,9 +595,10 @@ const WIDGET_CONTEXT_SHAPE = {
     fields: { id: "manifest.id", version: "manifest.version" },
   },
   user: {
-    description: "Signed-in user ({ id, email, displayName }).",
+    description:
+      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", displayName: "string" },
+    fields: { id: "string", email: "string", display_name: "string" },
   },
   workspace: {
     description:
@@ -546,19 +618,30 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   datastore: {
     description:
-      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) }, schema(table) -> Promise<{ id, name, columns: [...] }> }. `records` backs the query/record/mutation hooks; `schema` backs useDatastoreSchema() and resolves a table's column structure (no row data).",
+      "Injected @colixsystems/datastore-client instance. " +
+      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
+      "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function" },
+    fields: { records: "function", schema: "function", tables: "object" },
   },
   directory: {
     description:
-      "Read-only user directory. { listUsers(query?) -> Promise<Array<{ id, name, role }>> }. Backs useDirectory(); for chat people-lists / @-mention pickers / author-id resolution. Requires the directory.read:users scope.",
+      "Injected @colixsystems/directory-client instance. " +
+      "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
+      "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
+      "invites: { list(), revoke(id), resend(id) } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { listUsers: "function" },
+    fields: { users: "object", groups: "object" },
   },
   files: {
     description:
-      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+      "Injected @colixsystems/files-client instance, FLATTENED so file ops are top-level. " +
+      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData), folders: { list, create }, shares: { list, create, remove } }. " +
+      "Backs useFile(); the returned file already carries an absolute url the widget can drop into an <Image source>.",
     required: true,
     fields: { get: "function" },
   },
@@ -575,42 +658,17 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Incoming app-user payments (REQ-BILL-07-WIDGETPAY). { requestPayment({ amountCents, currency?, description, metadata? }) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
+      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
-  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
-  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
-  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
-  // APP_USER cannot forge scope claims, and the request is additionally
-  // gated by a SystemAcl `users.read` / `users.write` capability grant.
-  users: {
-    description:
-      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
-    required: true,
-    fields: {
-      listUsers: "function",
-      invite: "function",
-      deactivate: "function",
-      reactivate: "function",
-      remove: "function",
-    },
-  },
-  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
-  // backing useGroups(). Reads gated by `groups.read:*`; mutations by
-  // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
-  groups: {
-    description:
-      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
-    required: true,
-    fields: {
-      listGroups: "function",
-      create: "function",
-      remove: "function",
-      addMember: "function",
-      removeMember: "function",
-    },
-  },
+  // REQ-WSDK-DOMAIN-CLIENTS — the AppUser administration, AppUserGroup
+  // administration, and per-record VirtualPermission facades that used to
+  // live here (`users`, `groups`, `recordPermissions`) were folded into the
+  // injected domain-client instances: useUsers()/useGroups() read
+  // ctx.directory.{users,groups}; useRecordPermissions() reads
+  // ctx.datastore.records(table).permissions(record). See the `directory`
+  // and `datastore` slices above.
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -865,12 +923,44 @@ const CONTRACT = deepFreeze({
   // stored columnId to its column name / dataType / relation target at
   // runtime (Form Builder renders inputs by column type). Reads the existing
   // ACL-gated `GET /tables/:id` — structure only, no row data.
-  version: "1.7.0",
+  //
+  // 1.8.0: two additive features.
+  //  - REQ-WIDGET-ACTION — manifests may declare an optional `actions` array.
+  //    Each entry is a server-side action (cron- or record-triggered JS) the
+  //    operator enables per tenant; it runs in the existing isolated-vm action
+  //    runner, never in the rendered app. New contract fields
+  //    `actionTriggerTypes`, `actionScriptGlobals`, and `actionScriptMaxBytes`
+  //    let the docs + agent prompt + validator derive the grammar from one
+  //    source. New `ADMINISTRATION` manifest category (REQ-USERMGMT-06).
+  //  - REQ-ACL-06 — new `useRecordPermissions(tableId, recordId)` hook + the
+  //    `recordPermissions` host-context slice it reads + the `acl.write:records`
+  //    scope it gates on. Hits the existing REQ-ACL-06
+  //    /api/v1/tables/:tableId/records/:recordId/permissions REST surface; the
+  //    host normalises the wire shape into a single principalType+principalId
+  //    pair widgets branch on. Caller still needs canGrant on the target
+  //    record (REQ-ACL-RELINHERIT-05).
+  //
+  // 1.9.0: host-contract change (REQ-WSDK-DOMAIN-CLIENTS) — the host now
+  //    injects domain-client INSTANCES on the WidgetContext rather than
+  //    bespoke per-hook facades. ctx.datastore is a @colixsystems/datastore-client
+  //    (records(t).list now returns the { data, meta } envelope verbatim;
+  //    records(t).permissions(r) replaces the deleted ctx.recordPermissions),
+  //    ctx.directory is a @colixsystems/directory-client (users/groups
+  //    namespaces replace the deleted ctx.users / ctx.groups; list returns
+  //    envelopes), ctx.files is a flattened @colixsystems/files-client,
+  //    ctx.payments is a @colixsystems/payments-client. All rows/bodies are
+  //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
+  //    SDK stays duck-typed — it imports none of the four data SDKs. Minor
+  //    bump on the contract's pre-1.0 versioning (the breaking channel).
+  version: "1.9.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
   manifestCategories: CATEGORIES,
   manifestPlatforms: PLATFORMS,
+  actionTriggerTypes: ACTION_TRIGGER_TYPES,
+  actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
+  actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
   themeTokens: DEFAULT_THEME_TOKENS,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,