@mortar-ai/skill 0.5.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.
@@ -52,31 +53,52 @@ below; if platform provisioning fails, report that platform failure.
 
 1. Call `mortar_schema` before designing or changing backend data. It returns
    the current live schema, including console changes.
-2. For each schema change, call `mortar_migrate` once with one operation. It
-   applies the live change first; only after success does Fabric append a
-   migration record under `mortar/migrations/`.
-3. `mortar/migrations/` is a platform-owned output journal. Never create or edit
-   SQL there: a file in that directory does not execute or change the live
-   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. Install or update `@mortar-ai/client` with npm when needed and let npm own the
+2. Author database schema as exact Mortar logical SQL and submit `{ name, sql }`
+   to `mortar_migrate`. Fabric asks Mortar to parse a language-neutral typed
+   plan, applies the workspace review policy, writes those exact bytes under
+   `mortar/migrations/` with source-revision CAS, then Mortar re-verifies the
+   checksum and expected schema revision and commits the whole plan atomically.
+3. Use `mortar_resource` for non-database desired state. Function source and its
+   manifest live under `mortar/functions/<name>/`; bucket policy lives under
+   `mortar/storage/buckets/`; cron schedules live under `mortar/cron/`. Fabric
+   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`. 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.
-5. 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.
-6. Type-check and build. Handle every `{ data, error }` SDK 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`, `upsert_cron`, and `delete_cron`.
-Destructive and backend-changing operations must respect the workspace approval
-gate. This list is exhaustive: arbitrary PostgreSQL, data backfills, PL/pgSQL
-functions, transactions, and triggers are not migration inputs. If required
-behavior cannot be expressed by one of these operations, report the unsupported
-Mortar capability instead of authoring a SQL file that only looks executable.
+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
+`-- mortar:access public_insert` (or another access mode) immediately before a
+`CREATE TABLE` when the default `public_read` is wrong. Resource kinds are
+`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, `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
 
@@ -90,6 +112,11 @@ Mortar capability instead of authoring a SQL file that only looks executable.
 - 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.
@@ -105,6 +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, 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
@@ -138,8 +171,18 @@ sed -n '1,240p' /tmp/skills/mortar/references/storage.md
 ## Completion checklist
 
 - Live schema was read before schema design.
-- Every live schema change went through one approved `mortar_migrate` operation.
+- 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.5.0",
-  "content_sha256": "sha256:cbfe4219fa15934c523c1c22fe9795489539d0083d199624d2d15ac50bfe7755",
+  "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.5.0"
+    "version": "0.7.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mortar-ai/skill",
-  "version": "0.5.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

@@ -21,8 +21,8 @@ module, not a closed product taxonomy. A capability may span multiple
 application, primitive, account, or API packages, and one application module
 may support several capabilities.
 
-The current application modules are `auth`, `cron`, `data`, `files`, `queue`,
-`realtime`, and `secret`. Functions, comms, analytics,
+The current application modules are `auth`, `cron`, `data`, `files`,
+`migration`, `queue`, `realtime`, and `secret`. Functions, comms, analytics,
 accounts, and custom domains remain capabilities even when their implementation
 spans primitive, API, account, or other packages rather than a same-named
 application directory. `internal/usage` separately owns metering, quota,
@@ -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/automation.md

@@ -5,7 +5,7 @@ or atomic row-plus-job workflows. Cron and queue are shipped capabilities whose
 runtime availability depends on configuration; they are not “planned extension
 slots.”
 
-Fabric provisions schedules only through one `mortar_migrate` operation:
+Fabric provisions schedules only through one `mortar_resource` operation:
 `upsert_cron` creates or updates a schedule for an already deployed function,
 and `delete_cron` removes it. Direct cron list/create/patch/delete endpoints are
 trusted operator surfaces. Cron is normally enabled and can be disabled by the

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

package/references/functions.md

@@ -5,12 +5,17 @@ function logs. Cron is in `automation.md`; analytics is in `analytics.md`.
 
 ## Deploy and invoke functions
 
-Deploy or delete functions only through one `mortar_migrate` operation with
+Deploy or delete functions only through one `mortar_resource` operation with
 kind `deploy_function` or `delete_function`. Do not edit `mortar.config.json`,
-write migration files, or call operator/admin SDK methods from application
+directly write the protected function directory, or call operator/admin SDK methods from application
 code. Function list/deploy/delete/logs are trusted project or account/operator
 surfaces; the app-bundle client exposes invocation only.
 
+The desired-state directory contains `function.json` plus the runtime entrypoint:
+`index.js` for Node-compatible runtimes and `index.py` for Python-compatible
+runtimes. Switching runtime removes the stale entrypoint; deleting a function
+removes the manifest, both entrypoint forms, and the legacy flat `.js` artifact.
+
 Client bundles may invoke a function that the platform already deployed:
 
 ```ts