@mortar-ai/skill 0.6.0 → 0.7.0

package/README.md

@@ -34,8 +34,11 @@ experience.
 The skill teaches Claude:
 
 - **Core contract** — Fabric-owned client/config files, schema-first workflow,
-  one migration operation per call, supported migration kinds, access-policy
-  invariants, version boundaries, and completion checks.
+  real versioned SQL plan/apply, supported DDL, access-policy invariants,
+  OpenAPI-driven application code, version boundaries, and completion checks.
+- **OpenAPI reference** — the canonical Mortar REST contract is mirrored from
+  `mortar/docs/public/openapi.yaml` for on-demand operation/schema lookup; the
+  AI Turn writes project-language request and response code through Harness.
 - **Database reference** — CRUD, filters, atomic row mutations, trusted
   cross-table transactions, and ACID boundaries.
 - **Auth reference** — email/password, phone OTP, sessions, password reset, and
@@ -69,9 +72,11 @@ Idempotent — overwrites in place.
 
 ## Maintainer release
 
-`SKILL.md` and `references/` are the hand-edited instruction sources. Keep the
-core short and move capability detail into a routed reference. Regenerate the
-manifest and Harness copy before testing or publishing:
+`SKILL.md` and the Markdown files in `references/` are the hand-edited
+instruction sources. `references/openapi.yaml` is generated from the canonical
+`mortar/docs/public/openapi.yaml`; never edit the mirror directly. Keep the core
+short and move capability detail into a routed reference. Regenerate the
+manifest, OpenAPI mirror, and Harness copy before testing or publishing:
 
 ```bash
 npm run sync

package/SKILL.md

@@ -28,9 +28,10 @@ itself does not run on Mortar. Do not infer its setup from another BaaS.
   import { mortar } from '../../utils/mortar/client';
   ```
 
-- `src/integrations/mortar/client.ts`, its `types.ts`, and the WeChat equivalents
-  under `utils/mortar/` are platform-owned. Never create, overwrite, or replace
-  them.
+- `src/integrations/mortar/client.ts`, its compatibility `types.ts`, and the
+  WeChat equivalents under `utils/mortar/` are platform-owned wiring. Never
+  create, overwrite, or replace them. Generate application-owned request,
+  response, and domain types in ordinary project paths for the current runtime.
 - Never add `VITE_MORTAR_*`, `MORTAR_URL`, or client-side API-key environment
   variables. Never hand-write `createClient(...)`, `src/lib/mortar.ts`, or a
   second wrapper/client in a Fabric project.
@@ -63,19 +64,24 @@ below; if platform provisioning fails, report that platform failure.
    writes the approved artifact before reconciling the live resource.
 4. These source directories are platform-protected because direct edits would
    bypass plan/apply. Submit the exact source through the matching tool; do not
-   edit or create `mortar.config.json`. Do not edit generated
-   `integrations/mortar/types.ts`; Fabric regenerates it from the post-apply live
-   schema. The same schema can generate TypeScript, Swift, Kotlin, and Dart app
-   data types; those outputs are derived and never drive migration execution.
-5. Install or update `@mortar-ai/client` with npm when needed and let npm own the
+   edit or create `mortar.config.json`. Mortar returns contracts and live state,
+   never generated project files. The AI Turn owns runtime-specific app models
+   and request/response code through Harness; do not call or invent a Mortar
+   source-code-generation endpoint.
+5. Before writing application request/response code, locate the relevant
+   `operationId` in `references/openapi.yaml`, read its request, response, error,
+   security, and `x-mortar-trust-surface` fields, and combine that contract with
+   `mortar_schema` plus the project's language and conventions. Never expose an
+   operation marked `x-mortar-project-code: forbidden` in an app bundle.
+6. Install or update `@mortar-ai/client` with npm when needed and let npm own the
    lockfile. Atomic batches, server-side filtered mutations, and
    `DatabaseTransactions` require version 0.8.0 or newer. Do not rewrite
    unrelated dependencies.
-6. Before a multi-step mutation, choose the real consistency boundary. A
+7. Before a multi-step mutation, choose the real consistency boundary. A
    one-table batch or filtered mutation may use the public singleton;
    cross-table row + queue transactions require trusted server code; object
    storage and external services never join a PostgreSQL transaction.
-7. Type-check and build. Handle every `{ data, error }` SDK result in UI code.
+8. Type-check and build. Handle every `{ data, error }` SDK result in UI code.
 
 Supported database DDL is `CREATE TABLE`, `DROP TABLE`, `ALTER TABLE … ADD/DROP
 COLUMN`, `ALTER TABLE … SET ACCESS`, and `CREATE INDEX`. Put
@@ -84,7 +90,15 @@ COLUMN`, `ALTER TABLE … SET ACCESS`, and `CREATE INDEX`. Put
 `set_bucket_access`, `deploy_function`, `delete_function`, `upsert_cron`, and
 `delete_cron`; they belong to `mortar_resource`, never SQL. Destructive and
 backend-changing operations respect the workspace approval gate. Arbitrary
-PostgreSQL, data backfills, PL/pgSQL, transactions, and triggers are not inputs.
+PostgreSQL, `DEFAULT`, `UNIQUE`, `CHECK`, foreign keys, data backfills, PL/pgSQL,
+transactions, and triggers are not inputs.
+
+Every row already has server-owned `id`, `created_at`, and `updated_at`
+metadata. Do not declare those names as application columns or send them in
+ordinary insert/update payloads; only pass `id` as row identity through the
+documented upsert contract. They are flattened into SDK results and may be used
+for ordering or indexes. Today, `NOT NULL` enforces payload presence; logical
+type names guide application types but do not runtime-validate payload values.
 
 ## Access and safety invariants
 
@@ -98,6 +112,11 @@ PostgreSQL, data backfills, PL/pgSQL, transactions, and triggers are not inputs.
 - Generate an unguessable logical object key for each public upload.
 - Client-side filters are UX, not authorization. Choose a server-enforced access
   policy for private or owner-scoped rows.
+- Client validation and an in-flight submit guard are UX, not server validation
+  or retry-safe idempotency. Public row insert has no idempotency key or durable
+  uniqueness constraint. Never claim direct insert is exactly-once; when the
+  product requires durable deduplication, use a reviewed server-side contract
+  that actually implements it or state the limitation.
 - Never put `app` or `admin` keys, `DatabaseTransactions`, operator clients, or
   other privileged capabilities in Web, Desktop renderer, Keel/React Native, or
   WeChat bundles.
@@ -113,9 +132,12 @@ Agent Skills hosts resolve the same paths relative to this `SKILL.md`.
 
 - Database CRUD, atomic row mutations, trusted cross-table transactions, and
   exact ACID boundaries: `references/database.md`
-- Versioned SQL syntax, checksums/revisions, resource artifact layout, type
-  generation, legacy migrations, and the complete capability-to-source matrix:
+- Versioned SQL syntax, checksums/revisions, resource artifact layout, AI-owned
+  application types, legacy migrations, and the complete capability-to-source matrix:
   `references/schema-migrations.md`
+- The authoritative Mortar REST contract used to generate project-language
+  request/response code: `references/openapi.yaml`. Search by `operationId` and
+  read only the selected operation plus its referenced component schemas.
 - App-user signup/signin, OTP, session lifecycle, and private-user modeling:
   `references/auth.md`
 - Upload/download/list/signed URLs, immutable object versions, CORS, and
@@ -152,6 +174,15 @@ sed -n '1,240p' /tmp/skills/mortar/references/storage.md
 - Every database schema change used reviewed exact SQL through `mortar_migrate`;
   every function/bucket/cron change used `mortar_resource`.
 - Application code imports only the platform-owned singleton.
+- Application request/response and domain types were written by the AI in
+  ordinary project source after consulting the relevant OpenAPI operations and
+  live schema; Mortar did not return generated source files. Model real
+  boundaries (for example form input versus persisted data) and reuse
+  SDK-inferred response types when sufficient instead of adding ceremonial
+  duplicate aliases.
+- Application payloads do not redeclare or send server-owned row metadata, and
+  the UI does not overclaim client validation or duplicate suppression as a
+  durable backend guarantee.
 - No secret/admin client or hand-written fallback configuration entered the
   client bundle.
 - Every SDK error path is handled.

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": 1,
   "id": "mortar",
-  "version": "0.6.0",
-  "content_sha256": "sha256:f3cf01640a48dca83ccfe49a744c33355a5009567a1706d5c59528d6ddd3ee92",
+  "version": "0.7.0",
+  "content_sha256": "sha256:ec235e0f2e9c38e64ab906c8daca2daa98482313a4004fd1a73bc30f17671487",
   "source_repo": "liamxujia/appunvs",
   "source_path": "mortar/skill",
   "distributions": [
@@ -11,6 +11,6 @@
   ],
   "npm": {
     "package": "@mortar-ai/skill",
-    "version": "0.6.0"
+    "version": "0.7.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mortar-ai/skill",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Agent skill package for building Fabric applications on Mortar (BaaS), with compact core guidance and on-demand references.",
   "main": "index.js",
   "files": ["SKILL.md", "references", "manifest.json", "index.js", "README.md"],

package/references/architecture.md

@@ -89,7 +89,7 @@ deployment edge after Mortar verifies ownership.
 - **Trusted project/operator**: app/admin project keys in server, CI, CLI, MCP,
   or platform provisioning. Never ship these credentials or clients to a Web,
   Desktop renderer, Keel/React Native, or WeChat bundle.
-- **Account control plane**: account JWT or `mtr_pat_*` PAT against the apex
+- **Account control plane**: Account session JWT or `mtr_pat_*` PAT against the apex
   `_accounts` routes. These credentials manage projects and ownership; they are
   not interchangeable with project or app-user credentials.
 

package/references/control-plane.md

@@ -3,7 +3,7 @@
 Read this reference for Mortar accounts, projects, API keys, PATs, custom
 domains, plans, top-up, auto-top-up, capacity, or enterprise placement.
 
-The control plane uses the apex host and an account JWT or `mtr_pat_*` personal
+The control plane uses the apex host and an Account session JWT or `mtr_pat_*` personal
 access token. It manages account identity, project lifecycle, project API keys,
 PATs, project usage, domain claims, plan/top-up settings, and enterprise intent.
 These credentials are not app-user sessions and cannot be substituted for a

package/references/database.md

@@ -29,6 +29,37 @@ Updates and deletes use the same filter chain. Useful operators include `eq`,
 `neq`, ranges, `like/ilike`, `in`, `is`, `order`, `limit`, `single`, and
 `maybeSingle`.
 
+## System row metadata versus application payload
+
+Every stored row has server-owned `id`, `created_at`, and `updated_at` metadata.
+The SDK flattens that `RowMeta` beside the application payload when returning a
+row. Do not declare those names as logical application columns and do not send
+them in ordinary insert/update payloads. The documented upsert contract is the
+exception: it accepts `id` as row identity and removes system metadata from the
+stored application payload. Use the server-generated `created_at` for ordering,
+filters, and indexes instead of creating a second timestamp column.
+
+Mortar's current logical schema enforces required-field presence through `NOT
+NULL`. Type spellings drive the language-neutral schema and application types,
+but the row API does not yet runtime-validate every value against those type
+names. `DEFAULT`, `UNIQUE`, `CHECK`, and foreign-key constraints are not
+supported logical DDL. Client-side format, range, and length checks remain UX;
+do not describe them as database enforcement.
+
+## Duplicate suppression is not durable idempotency
+
+Disabling a submit button while a request is in flight prevents rapid duplicate
+clicks in that mounted client. It does not make a row insert retry-safe. The
+public insert API has no idempotency-key contract or durable uniqueness
+constraint, and the SDK intentionally does not automatically retry this
+non-idempotent POST. A client-side select-then-insert check is still racy and is
+often unavailable under `public_insert` because anonymous reads are denied.
+
+If the product requires exactly-once submission or durable deduplication, do
+not claim direct public insert satisfies it. Use a reviewed supported
+server-side contract that really performs atomic deduplication, or state that
+the guarantee is not currently available for that client path.
+
 ## Atomic row mutations
 
 Pass an array when every insert or upsert must succeed or fail together. Mortar