@miosa/sdk 3.0.1 → 3.1.0

package/README.md

@@ -55,6 +55,7 @@ await sbx.pause();
 | `miosa.sandboxes` | Lightweight code-execution VMs — exec, files, snapshots, previews |
 | `miosa.computers` | Full Linux desktop VMs with desktop control for agents |
 | `miosa.deployments` | Versioned production releases with rollback |
+| `miosa.appDocuments` | Durable generated apps with exact-version review approvals and immutable publication bindings |
 | `miosa.databases` | Managed Postgres / Redis lifecycle |
 | `miosa.storage` | S3-compatible object storage |
 | `miosa.volumes` | Persistent block storage |
@@ -69,6 +70,38 @@ await sbx.pause();
 | `miosa.completions` | OpenAI-compatible chat completions with SSE streaming |
 | `miosa.embeddings` | OpenAI-compatible embedding vectors |
 
+## Durable generated apps
+
+App Documents persist the generated app contract outside the browser.
+They are workspace-scoped and include the view, declared capabilities, connectors, collections, automations, and component pins.
+Native rendering authority is a separate approval pinned to the current canonical version hash.
+Editing the document changes the hash and invalidates the old approval.
+
+```ts
+const app = await miosa.appDocuments.create({
+  workspaceId: "workspace-id",
+  name: "Clinic triage",
+  document: {
+    id: crypto.randomUUID(),
+    name: "Clinic triage",
+    format: "miosa-app/v1",
+    view: { kind: "generated", source: "<main>Triage</main>" },
+    capabilities: ["computer.exec"],
+    collections: ["tickets"],
+    connectors: ["linear"],
+    automations: [],
+    pins: [],
+  },
+});
+
+const approval = await miosa.appDocuments.approveExactVersion(
+  app.id,
+  "Reviewed for exact release publishing",
+);
+
+await miosa.appDocuments.revokeApproval(app.id, approval.id);
+```
+
 ## Connect vs Egress
 
 Use **Connect** when your product needs to manage provider credentials for
@@ -258,6 +291,30 @@ const deployment = await sbx.deploy({
 });
 ```
 
+To publish the exact snapshot that passed QA instead of whatever the editable
+sandbox holds right now, use `deploySnapshot`. It forks the snapshot into a
+temporary release sandbox, deploys that fork, and destroys it again, so the
+source sandbox is never mutated:
+
+```ts
+const snap = await sbx.snapshots.create("qa-approved");
+
+const release = await sbx.deploySnapshot(snap.id, {
+  name: "clinic-intake",
+  outputPath: "/workspace/dist",
+  entrypoint: "index.html",
+});
+
+console.log(release.source_snapshot_id, release.release_sandbox_id);
+```
+
+The result always carries `source_snapshot_id` and `release_sandbox_id` for
+provenance. Pass `{ cleanup: false }` as the third argument to keep the release
+sandbox for inspection. If the release sandbox could not be destroyed, the
+deployment still succeeds and `release.release_cleanup_error` explains why; when
+the deploy itself fails and the release sandbox survives, the thrown error
+carries the same fields so the leftover sandbox can be cleaned up by id.
+
 For workspace App Engine, publish from the same sandbox but choose the
 App Engine target: