@mortar-ai/skill 0.5.0 → 0.6.0

package/SKILL.md

@@ -52,31 +52,39 @@ 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`. 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
    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
+6. 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.
+7. 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.
+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, data backfills, PL/pgSQL, transactions, and triggers are not inputs.
 
 ## Access and safety invariants
 
@@ -105,6 +113,9 @@ 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:
+  `references/schema-migrations.md`
 - 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,7 +149,8 @@ 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.
 - No secret/admin client or hand-written fallback configuration entered the
   client bundle.

package/manifest.json

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

package/package.json

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

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/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

package/references/schema-migrations.md

@@ -0,0 +1,98 @@
+# Schema migrations and resource artifacts
+
+Read this reference when authoring backend source, reviewing a typed migration
+plan, resolving revision/checksum conflicts, generating app-data types, or
+deciding whether a Mortar capability belongs in source at all.
+
+## One canonical plan, four derived type targets
+
+Mortar parses SQL into `mortar.migration-plan.v1`, a language-neutral JSON plan.
+That plan—not TypeScript, Swift, Kotlin, or Dart code—is the execution contract.
+After a successful apply, the canonical live schema may generate app-data models
+for all four SDK languages. Generated models are downstream output; never edit
+them to request a schema change.
+
+## Versioned database SQL
+
+Submit exact SQL through `mortar_migrate`:
+
+```sql
+-- mortar:access public_insert
+CREATE TABLE submissions (
+  email text NOT NULL,
+  score integer,
+  metadata jsonb
+);
+
+ALTER TABLE submissions ADD COLUMN reviewed boolean NOT NULL;
+CREATE INDEX submissions_reviewed ON submissions (reviewed, created_at);
+ALTER TABLE submissions SET ACCESS app_only;
+```
+
+The parser accepts common PostgreSQL type spellings and canonicalizes them to
+Mortar's logical types: `text`, `number`, `bool`, `json`, `timestamp`, and
+`uuid`. It rejects row data, backfills, triggers, stored procedures, transaction
+control, and calls that pretend functions/storage/cron are SQL.
+
+Plan/apply guarantees:
+
+- SHA-256 covers the exact SQL bytes written to source.
+- `migration_id + checksum` is idempotent; reusing an id with different bytes is
+  a conflict.
+- Every tenant has a monotonic schema revision. Apply fails if the reviewed
+  `expected_revision` is stale.
+- All logical schema operations and the revision ledger row commit in one
+  tenant-scoped PostgreSQL transaction.
+- Source is written with Fabric's source-revision CAS before apply. If apply
+  fails, the file remains an honest pending migration that can be fixed or
+  retried; no live mutation is wrapped afterwards as fake SQL.
+
+`DROP TABLE` removes its rows and `DROP COLUMN` removes the schema declaration;
+both are destructive plan diagnostics. Changing access must use `ALTER TABLE …
+SET ACCESS`, never drop/recreate.
+
+## Non-database desired state
+
+Use `mortar_resource` so Fabric writes the exact artifact before reconciling the
+live resource:
+
+| Source path | Managed desired state |
+|---|---|
+| `mortar/functions/<name>/index.js` or `index.py` | Runtime-specific function source |
+| `mortar/functions/<name>/function.json` | Runtime and authoritative entrypoint |
+| `mortar/storage/buckets/<name>.json` | Bucket access policy |
+| `mortar/cron/<name>.json` | Schedule, target function, enabled state |
+
+Deleting a function or cron removes its current-state artifact. These resources
+may call external systems and do not join a database migration transaction.
+
+## Complete capability-to-source matrix
+
+“Mortar supports it” does not imply it should be a source artifact:
+
+| Capability | Source authority | Why |
+|---|---|---|
+| Database tables/columns/access/index intent | Versioned SQL migration | Durable ordered schema with atomic revision ledger |
+| Functions | Function directory | Executable source plus runtime metadata, not SQL |
+| Bucket policy | Bucket JSON | Durable access policy; object bytes are runtime data |
+| Cron schedules | Cron JSON | Durable desired schedule; executions are runtime state |
+| Auth users/sessions/OTP/reset | None | Identity and credentials are runtime/security state |
+| Database rows and row transactions | None | Application data, not schema |
+| Stored files and signed URLs | None | Runtime objects and ephemeral authorization |
+| Realtime row changes/broadcast/presence | None | Events and presence are runtime/ephemeral state |
+| Queue jobs/claims/retries | None | Runtime work state; enqueue may join a row transaction |
+| Analytics events/summaries | None | Runtime observations and derived reporting |
+| Email/SMS sends | None | External side effects; make business workflows idempotent |
+| Secret values | Encrypted Mortar secret store only | Values must never enter project source; source may document names in application-owned docs |
+| Usage, logs, billing ledger | None | Platform observations and accounting authority |
+| Projects, keys, PATs, domains, plans, capacity | None | Account/control-plane state |
+
+## Legacy projects
+
+Do not automatically replay or rewrite an existing migration history merely
+because this workflow shipped. Old files can describe already-live schema, and
+some projects may keep explicit operator SQL under `mortar/operations/` for
+capabilities outside Mortar logical DDL. Treat those files as legacy history;
+new supported schema changes start at the next migration id. Arbitrary operator
+SQL remains a separately reviewed operational path and is not silently claimed
+as replayable Mortar migration source.

package/references/storage.md

@@ -23,6 +23,11 @@ retryable cleanup. Never construct, persist, or expose an internal physical
 object key. Application projects do not run or author the platform storage
 migration.
 
+Set durable bucket access through `mortar_resource`; Fabric writes
+`mortar/storage/buckets/<name>.json` before reconciling the live policy. Object
+bytes, logical object keys, signed URLs, and cleanup jobs remain runtime state
+and never enter this source artifact.
+
 This protocol prevents Mortar metadata from pointing at a partial upload, but a
 separate application row and an object upload are not one transaction. Generate
 an unguessable logical key. For a simple workflow, upload first and write the