@mortar-ai/skill 0.5.0 → 0.7.0

package/references/schema-migrations.md

@@ -0,0 +1,117 @@
+# Schema migrations and resource artifacts
+
+Read this reference when authoring backend source, reviewing a typed migration
+plan, resolving revision/checksum conflicts, writing application data types, or
+deciding whether a Mortar capability belongs in source at all.
+
+## One canonical plan, AI-owned application types
+
+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.
+Mortar does not generate project source. After apply, the AI Turn combines the
+canonical live schema, the relevant operations from `references/openapi.yaml`,
+and the project's runtime conventions to write application-owned models and
+request/response code through Harness. Those files are downstream consumers;
+never edit them to request a schema change.
+
+Search the OpenAPI by stable operation ID, for example:
+
+```sh
+rg -n 'operationId: (insertDatabaseRows|listDatabaseRows)' \
+  /tmp/skills/mortar/references/openapi.yaml
+```
+
+Read the selected operation and every referenced component schema before
+writing code. An operation marked `x-mortar-project-code: forbidden` belongs to
+Harness/control-plane tooling and must never be called from a user app.
+
+## 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`. `id`, `created_at`, and `updated_at` are server-owned row metadata, so
+they are not declared as application columns; system timestamps may still be
+used in an index, as above. `NOT NULL` enforces required-field presence. Logical
+type names inform project-language types but do not currently runtime-validate
+every row value. The parser rejects `DEFAULT`, `UNIQUE`, `CHECK`, foreign keys,
+row data, backfills, triggers, stored procedures, transaction control, and calls
+that pretend functions/storage/cron are SQL. Never invent unsupported DDL or
+describe client validation as a database constraint.
+
+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