@mortar-ai/skill 0.2.0 → 0.3.0

package/README.md

@@ -35,6 +35,12 @@ The skill teaches Claude:
 - **SDK surface** — the `mortar.from()` / `auth` / `storage` /
   `realtime` / `compute` / `usage` / `cron` / `queue` / `comms`
   accessors + the account-scope `AccountClient`; which one to reach for
+- **Transaction boundaries** — atomic row batches and filtered mutations,
+  trusted cross-table row + PostgreSQL queue transactions, and why privileged
+  transaction clients must never enter browser/mobile bundles
+- **Storage consistency** — immutable physical object versions, atomic metadata
+  pointer switches, durable cleanup, and why object storage is not part of a
+  PostgreSQL ACID transaction
 - **CLI commands** — `mortar login / use / db / storage / compute /
   cron / queue / domains / comms / keys / tokens / topup / usage`
 - **MCP tools** — the 40 `mortar_*` tools and when an agent should use

package/SKILL.md

@@ -1,10 +1,11 @@
 ---
-name: Mortar
-description: Required guidance for Fabric apps that need a database, backend, authentication, persistence, file storage, realtime collaboration, cloud functions, or product analytics.
-activation: auto
-priority: high
-triggers:
-  - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, storage, upload, 文件, realtime, 实时, collaboration, compute, cloud, 云端]
+name: mortar
+description: Build or change Fabric applications that use Mortar for database, auth, storage, realtime, compute, or analytics. Use for Mortar schema and provisioning, SDK integration, RLS, transactions, or storage consistency; not for Fabric's own control plane or a different backend.
+metadata:
+  activation: auto
+  priority: high
+  triggers:
+    - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, transaction, 事务, ACID, storage, upload, 文件, realtime, 实时, collaboration, compute, cloud, 云端]
 ---
 
 # Mortar for Fabric applications
@@ -59,8 +60,16 @@ below; if platform provisioning fails, report that platform failure.
    tenant. Do not edit or create `mortar.config.json`. Do not edit generated
    `integrations/mortar/types.ts`; Fabric regenerates it from the live schema.
 4. Run `npm install @mortar-ai/client` if the dependency is absent, then write app
-   code using the injected singleton.
-5. Type-check and build. Handle every `{ data, error }` result in UI code.
+   code using the injected singleton. Atomic batches, server-side filtered
+   mutations, and `DatabaseTransactions` require `@mortar-ai/client` 0.8.0 or
+   newer. If an existing project needs one of those capabilities and pins an
+   older version, update that dependency with npm and let npm update its lockfile;
+   do not rewrite unrelated dependencies.
+5. Before writing a multi-step mutation, choose the supported consistency
+   boundary: one-table batches and filtered mutations can use the bundle-safe
+   singleton; cross-table row + queue transactions require trusted server code;
+   object storage and external services never join a PostgreSQL transaction.
+6. Type-check and build. Handle every `{ data, error }` result in UI code.
 
 Supported migration kinds are `create_table`, `drop_table`, `set_table_access`,
 `add_column`, `drop_column`, `create_index`, `set_bucket_access`, `deploy_function`, `delete_function`,
@@ -103,13 +112,87 @@ const { data: created, error: insertError } = await mortar
   .insert({ title: 'Ship', done: false, user_id: userId })
   .select()
   .single();
-
 ```
 
 Updates and deletes use the same filter chain. Useful operators include `eq`,
 `neq`, ranges, `like/ilike`, `in`, `is`, `order`, `limit`, `single`, and
 `maybeSingle`.
 
+### Atomic row mutations
+
+Pass an array when every insert or upsert must succeed or fail together. Mortar
+sends at most 200 rows in one request and executes the batch in one
+tenant-scoped PostgreSQL transaction. For upsert, a row with an `id` replaces
+that row's data; a row without an `id` inserts. Do not use a loop or
+`Promise.all` when partial completion would break an invariant.
+
+```ts
+const { data: createdTodos, error: batchError } = await mortar
+  .from('todos')
+  .insert([
+    { title: 'Prepare', done: false, user_id: userId },
+    { title: 'Ship', done: false, user_id: userId },
+  ])
+  .select();
+if (batchError) throw new Error(batchError.message);
+
+const { data: changedTodos, error: updateError } = await mortar
+  .from('todos')
+  .update({ done: true })
+  .eq('user_id', userId)
+  .eq('archived', false)
+  .select();
+if (updateError) throw new Error(updateError.message);
+```
+
+Filtered `update` and `delete` select and mutate all matching rows inside one
+server-side transaction. Do not pre-select IDs and then update/delete them one
+at a time: that creates a race and loses the all-or-nothing guarantee. Chain
+`.select()` only when the app needs the affected rows returned.
+
+### Cross-table transactions are server-only
+
+`DatabaseTransactions` can atomically combine up to 200 cross-table row
+`insert` / by-ID `update` / by-ID `delete` operations and PostgreSQL-backed
+queue `enqueue` operations. It is intentionally not attached to the injected
+`mortar` singleton and requires an `app` or `admin` key. Its `execute` method
+throws on failure, so use `try`/`catch`, not a `{ data, error }` envelope.
+
+```ts
+import { DatabaseTransactions } from '@mortar-ai/client';
+
+const transactions = new DatabaseTransactions(serverOnlyMortarOptions);
+
+try {
+  const results = await transactions.execute([
+    { op: 'insert', table: 'orders', data: { customer_id: customerId, total } },
+    { op: 'enqueue', type: 'send_receipt', payload: { customer_id: customerId } },
+  ]);
+  console.log(results);
+} catch (error) {
+  // Nothing committed. Report or retry the whole idempotent operation.
+  throw error;
+}
+```
+
+Never instantiate `DatabaseTransactions` in Web, Desktop renderer,
+Keel/React Native, or WeChat client code. Never add an app/admin key to a
+client-side environment variable or source file. Use this API only in an
+already-approved trusted server environment that holds the key. If a Fabric
+project has no such path, report cross-table ACID as unsupported instead of
+simulating it with several public-client calls. A transactional queue enqueue
+also requires Mortar's PostgreSQL queue backend; otherwise the whole request
+fails without committing row changes.
+
+### Exact ACID boundary
+
+Mortar provides true ACID only for work executed in the same tenant-scoped
+PostgreSQL transaction: atomic row batches, filtered row mutations, and the
+trusted cross-table row + PostgreSQL queue API above. Object storage,
+compute/functions, communications providers, analytics delivery, and other
+external systems do not participate in that transaction. Never describe a
+workflow spanning them as one ACID transaction or claim two-phase commit.
+
 ## App-user authentication
 
 Auth sessions are persisted and attached to later database, storage, realtime,
@@ -153,6 +236,22 @@ const { data: signed, error: signError } = await bucket.createSignedUrl(path, 36
 const { error: removeError } = await bucket.remove([path]);
 ```
 
+Applications address files by their stable logical `path`. Mortar stores new
+uploads under immutable internal physical versions, then atomically switches
+its PostgreSQL metadata pointer and durably schedules orphan/replaced versions
+for retryable cleanup. Never construct, persist, or expose Mortar's internal
+physical object key. Existing logical paths remain compatible, and application
+projects do not run or author the platform storage migration.
+
+This protocol keeps Mortar's own file metadata from pointing at a partial
+upload, but it does not make a separate application row and an object upload
+one transaction. When a business row must reference a file, generate an
+unguessable logical key. For a simple workflow, upload first and write the
+business row only after upload succeeds. For recoverable workflows, create a
+row with a stable idempotency key and `pending` state, upload, then mark it
+`ready`; reconcile stale rows to `failed` or retry them. Do not issue a database
+write and `bucket.upload()` concurrently and call the result atomic.
+
 Downloads mint a short-lived URL and fetch the object directly from the storage
 backend. Reuse `signed.signedUrl` until it nears expiry when rendering media.
 Prefer the signed URL directly in `<img src>`, `<video src>`, or `<audio src>`;

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": 1,
   "id": "mortar",
-  "version": "0.2.0",
-  "content_sha256": "sha256:dd11d5e635f47e64303927fd4af21b0f8a9aef8836a17c3a592eecb69cc75325",
+  "version": "0.3.0",
+  "content_sha256": "sha256:c69dab74ad4a377086c0c883c4d400770600738de2741778fad21ec27e925f27",
   "source_repo": "liamxujia/appunvs",
   "source_path": "mortar/skill/SKILL.md",
   "distributions": [
@@ -11,6 +11,6 @@
   ],
   "npm": {
     "package": "@mortar-ai/skill",
-    "version": "0.2.0"
+    "version": "0.3.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mortar-ai/skill",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent skill package for building Fabric applications on Mortar (BaaS), distributed from one versioned SKILL.md with a content-addressed manifest.",
   "main": "index.js",
   "files": ["SKILL.md", "manifest.json", "index.js", "README.md"],