@happyvertical/smrt-app-shell 0.0.0-stage → 0.60.17

package/AGENTS.md

@@ -0,0 +1,99 @@
+# @happyvertical/smrt-app-shell
+
+An ordinary smrt app (SvelteKit + adapter-node, app-runtime **local** profile)
+that builds and runs a person's own smrt app from a versioned JSON definition,
+for one person: the owner. Epic #4867; this package is #4872. The engine is
+documented in [agents/engine.md](agents/engine.md) (it must not import
+SvelteKit or `src/lib`). README has the route and JSON contracts.
+
+## Where things live
+
+| Path | What |
+|---|---|
+| `src/engine/` | `AppHost`, worker thread, migrations, QuickJS sandbox. Finished and tested on its own. |
+| `src/lib/objects/` | Shell models (`objectsDir` in `vite.config.ts`): `App`, `AppVersion`, `Approval`, `AssistantThread`, `AssistantMessage`. |
+| `src/lib/server/smrt.ts` | `createSmrtSvelteKitRuntime`, `prepareDatabase`, `configureShell`. |
+| `src/lib/server/schema.ts` | `prepareShellSchema(db)`: additive first-run schema. |
+| `src/lib/server/host.ts` | Holders: shell db, data root, the one lazily opened `AppHost`. |
+| `src/lib/server/version-store.ts` | `ShellVersionStore` (engine `VersionStore` on `AppVersion` + the `App` row). |
+| `src/lib/server/owner.ts` | Owner check, `Principal`, `assertOwner`, `runAs`. |
+| `src/lib/server/approvals.ts` | Approval service; the only place `approved: true` is set. |
+| `src/lib/server/builder.ts` | `runCommand`/`runAppTool`/`runRest`/`requestRecordDelete`: execute or turn into an Approval. |
+| `src/lib/server/catalog.ts`, `policy.ts`, `mcp-server.ts` | Merged tool catalog, the one policy, the `/mcp` server. |
+| `src/lib/server/http.ts`, `events.ts` | Route plumbing; in-process event bus for SSE. |
+| `src/lib/server/assistant/`, `src/lib/assistant/` | Assistant: turn loop, hold, config, routes (`mountAssistantRoutes`), thread store; dock UI, pure reducer/stream parser, `guidance/system.md`. |
+| `src/routes/` | `/api/shell/*`, `/api/app/[...path]`, `/api/events`, `/mcp`, `/setup`, health. UI pages are placeholders. |
+
+## Invariants
+
+- **Owner only.** Owner = ACTIVE membership holding the system `owner` role,
+  looked up in shell.db on every check (`isOwner`); nothing in a token, header
+  or body is trusted. Every route calls `ownerOf(event)` (401/403, same-origin
+  for writes). Every `App.*` builder method and `Approval.decide/pending`
+  starts with `assertOwner()`, which reads the async scope's tenant context
+  (the session handler sets it; routes and `dispatchTool` use `runAs`).
+  `operationPermissions` only aliases the generated routes onto CRUD grants, a
+  member role may hold those, so `assertOwner` is the rule.
+- **Approval gate.** A risky builder command, `<model>_delete` tool, REST
+  `DELETE` or record delete never runs: it becomes an `Approval`
+  (`pending_approval`, idempotent per identical pending action). Only
+  `decideApproval` (called by `Approval.decide`) passes the engine's
+  `approved: true`; `invariants.test.ts` fails if any other source does, or if
+  a route reads an `approved` input. The engine refuses without it as well.
+  `undo` is risky when the version being undone has a type conversion (it would
+  overwrite newer values with the archived originals); `POST /api/shell/undo`
+  then answers 202 `pending_approval` and History links to /approvals. The
+  assistant pauses only on the out-of-band `CatalogResponse.pending` marker set
+  by `dispatchTool` (from `requestApproval`), never on result text, and shows the
+  stored Approval's summary and preview. `/api/app/sync/apply` and other
+  reserved core endpoints are refused (only the app's own collections are
+  served). Snapshots are retained (20 `method-*`; clean up prunes old
+  `migrate-*`/`schema-*`).
+- **Decorator configs are literals** (`@smrt({...})` on `App`, `Approval`). The
+  scanner reads them statically; a shared constant silently falls back to full
+  CRUD routes. Collections are undecorated. The shell models expose only their
+  custom operations (no generated list/get/create/update/delete); keep
+  `mcp.test.ts` asserting that.
+- **One policy.** `toolsFor(principal)` / `authorizeCall(principal, name)` /
+  `callTool(...)` in `policy.ts` are the only entry for MCP tools (the `/mcp`
+  route and the assistant). Non-owner: empty list, 403. App tools never shadow
+  shell tools (`app_*`, `approval_*`; `defineModel` refuses those names).
+- **Data layout.** `shell.db` is app-runtime's database file; the user app is
+  `<data root>/user-app/` (`app.db`, `snapshots/`, archives inside app.db):
+  plain files and directories inside the app-runtime data root, no symlinks, so
+  the encrypted backup seals them. `PORT` and `SMRT_DATA_DIR` are honored (the
+  desktop sidecar contract); health is `/api/_runtime/health`.
+- **App-subclass rule** lives in the engine (`enableRecipe` creates app
+  subclasses of shipped models). The shell never registers user models in its
+  own registry.
+- **`prepareDatabase` consumer.** app-runtime's first-run schema hook is
+  smrt#4835 (pending, another session). Until it lands the shell passes
+  `prepareShellSchema` as the existing `prepareDatabase` option. Do not edit
+  `packages/app-runtime` from here. Switching is one line in `smrt.ts`.
+  `prepareShellSchema` only creates missing tables (no ALTER): a model that
+  gains a column later needs a real migration step added there.
+- **Generated change feed** (`_changes`, `_events`) is limited to the owner by
+  `change-feed.ts`.
+- `/mcp` is stateless Streamable HTTP, so `tools/list_changed` cannot be
+  pushed on it; the UI and assistant listen to `/api/events` (`changed`).
+  `tools/list` is sent with `ttlMs: 0`.
+- Never log request bodies, tokens or definitions; `errorResponse` returns
+  messages only, 500s are generic.
+
+- **Assistant.** Same policy as `/mcp` (`toolsFor`/`callTool`). No tool
+  decides approvals (`approval_decide` is not in the catalog, and
+  `ASSISTANT_DENIED_TOOLS` repeats it): only the signed-in owner does, in the UI. A risky call is held (`holdForUser`) on its Approval; only the
+  owner's `Approval.decide` applies it. The loop is bounded (`DEFAULT_LIMITS`),
+  serial, aborts on disconnect. API key only: `config.ts` refuses
+  `claude-cli`/`chatgpt-plan`; never spawn a CLI. Model errors are never
+  forwarded or logged beyond class/code (SDK messages can echo keys). Tests use
+  a stub through `modelFactory`.
+
+## Tests and build
+
+`vitest run` (in-process, SQLite, temp dirs; `test-support.ts` seeds an owner
+and a member; it opens the real driver because the vitest setup would
+pre-create tables). `pnpm build` (tsc engine, `svelte-kit sync`, `vite build`;
+the smrt() plugin generates `src/routes/api/{apps,approvals,_changes,_events,
+_resources}`: git-ignored) and `pnpm typecheck` must pass. The `smrt()` plugin
+needs the models in `src/lib/objects`, set via `objectsDir`.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# @happyvertical/smrt-app-shell
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A smrt app that builds and runs a person's own smrt app from definitions. One
+person (the owner) signs in, changes the app (models, fields, code methods,
+recipes) through builder operations or the assistant, risky changes wait for the
+owner's approval, and every change is versioned and can be undone.
+
+```
+smrt-app-shell (SvelteKit + adapter-node, app-runtime local profile)
+├── shell.db (the app-runtime database)  users, sessions, App, AppVersion, Approval
+├── src/engine                           AppHost: worker thread, migrations, sandbox
+└── <data root>/user-app/                app.db, snapshots (plain files; the newest 20 `method-*` are kept, clean up prunes old migration ones)
+```
+
+## Run it
+
+Build once, then set up the data folder and the owner link, then start the
+server. Use the same `PORT` for setup and start, because the one-time link
+carries it. Keep the data folder outside the checkout.
+
+```sh
+pnpm --filter @happyvertical/smrt-app-shell build
+cd packages/app-shell
+export SMRT_DATA_DIR=<a new folder outside the checkout> PORT=4796 HOST=127.0.0.1 ORIGIN=http://127.0.0.1:4796
+
+node ../cli/bin/smrt.js app setup   # or `smrt app setup`: creates the data folder and issues the one-time owner link
+node build                          # start the server with the same exports
+smrt app open                       # opens the one-time /setup?token=... link; create the owner there
+```
+
+`node build` alone never prints a setup link: the shell passes no
+`onBootstrapInvitation`, so the link comes from `smrt app setup` (it is saved in
+the app's state folder, not the data folder). If the link is lost, stop the
+server and run `smrt app recover` for a new one. Setup is loopback only and
+single use. Health: `GET /api/_runtime/health`.
+
+## Builder operations (MCP tools and `POST /api/apps/<operation>`)
+
+The same names and parameters on both surfaces. A wrong-shaped argument is a
+400 that says what to send (never a 500); a risky operation answers 202
+`pending_approval` (REST) or returns it as the tool result (MCP).
+
+| Operation (tool) | Parameters |
+|---|---|
+| `defineModel` (`app_definemodel`) | `name`, `fields?` (`{ fieldName: FieldDef }`), `label?` |
+| `addField` (`app_addfield`) | `model`, `field`, `definition` (a FieldDef) |
+| `changeFieldType` (`app_changefieldtype`) | `model`, `field`, `definition` (a FieldDef; REST also accepts the older `to`) |
+| `hideField`, `removeField` | `model`, `field` |
+| `renameField` | `model`, `from`, `to` |
+| `removeModel` | `model` |
+| `addMethod` | `model`, `name`, `method` (`{ description, code, params? }`) |
+| `enableRecipe` | `recipe` |
+| `cleanUp` | `keep?` |
+| `importTemplate`, `exportTemplate` | `data`, `includeRecords?` |
+
+A FieldDef is `{ type, label?, required?, choices?, ref? }`; `type` is one of
+text, number, integer, boolean, date, money, choice, reference, json. Field names
+are camelCase (`dueDate`).
+
+## Contracts for the UI and the assistant
+
+Every route needs the owner's session cookie (401 signed out, 403 not the
+owner). Writes must be same-origin `application/json`. Errors are
+`{ error, code? }`. Live updates: `GET /api/events` (below).
+
+| Route | Body | Response |
+|---|---|---|
+| `GET /api/shell/describe` | | `{ name, version, recipes, models: { [Model]: { kind: 'app'\|'shipped-subclass', label, table, className, extends, fields: { [name]: FieldDef }, ownFields: string[], methods: { [name]: { description, params } } } }, pendingApprovals }` |
+| `GET /api/shell/history` | | `{ versions: { version, parent, author, summary, createdAt, purged, current }[] }` oldest first |
+| `POST /api/shell/undo` | none | change result `{ version, summary, statements, snapshot, appRestartMs, ... }`; 409 if purged; **202** `PendingApproval` (with `preview.replaced`, the rows that would be overwritten) when the change being undone converted a field's type |
+| `GET /api/shell/approvals?status=` | | `{ approvals: ApprovalView[], pending }`; `status` is `pending`, `approved`, `denied` or `failed` |
+| `POST /api/shell/approvals/<id>` | `{ approve: boolean }` | `{ id, status: 'approved'\|'denied'\|'failed', result?, error? }`; 404 unknown, 409 already decided |
+| `GET /api/shell/records/<Model>?limit=` | | `{ records: object[] }` |
+| `POST /api/shell/records/<Model>` | the record's fields | 201 the record |
+| `GET /PUT /api/shell/records/<Model>/<id>` | PUT: changed fields | the record |
+| `DELETE /api/shell/records/<Model>/<id>` | | **202** `PendingApproval`; nothing is deleted until approved |
+| `/api/app/<route>` (any method) | as the app's REST | the app's generated REST (`/api/app/chores` is the app's `/api/chores`); `DELETE` answers **202** `PendingApproval`; only the app's own collection routes are served (`sync/apply`, `_changes`, `_events` and unknown collections are 404) |
+| `GET /api/events` | | server-sent events |
+| `POST /mcp` | MCP Streamable HTTP | shell tools plus app tools, one policy |
+
+`PendingApproval = { status: 'pending_approval', approvalId, summary, preview }`.
+`ApprovalView = { id, status, summary, preview, action, requestedBy, decidedBy, decidedAt, result, createdAt }`
+where `action` is `{ kind: 'command', command } | { kind: 'tool', name, args } | { kind: 'rest', method, url } | { kind: 'record-delete', model, id }`.
+
+`GET /api/events` sends `event: ready`, then `event: shell` with JSON
+`{ type: 'changed', version, summary }` (definition changed: reload
+`describe`, the menu and the tool catalog), `{ type: 'records', model }`
+(`model` may be null: reload lists) and `{ type: 'approval', id, status, summary }`
+(`pending`, `approved`, `denied`, `failed`). A `: ping` comment every 25 s.
+
+Builder operations are static methods on `App` and also appear as generated
+REST (`POST /api/apps/<op>`) and MCP tools (`app_definemodel`, `app_addfield`,
+`app_hidefield`, `app_renamefield`, `app_removefield`, `app_changefieldtype`,
+`app_removemodel`, `app_addmethod`, `app_enablerecipe`, `app_undo`,
+`app_cleanup`, `app_exporttemplate`, `app_importtemplate`, `app_describe`,
+`app_history`), plus `approval_pending`. There is no tool to decide an approval: only the
+owner, signed in, decides in the UI, so no model-driven client (the assistant
+or an outside MCP client) can approve its own call. The risky ones
+(`addMethod`, `removeField`, `removeModel`, `changeFieldType`, `cleanUp`, an
+`importTemplate` carrying code) return `PendingApproval` instead of applying.
+
+### Policy module for the assistant
+
+`src/lib/server/policy.ts`:
+
+- `toolsFor(principal): Promise<CatalogTool[]>`: the merged catalog (`{ name, description, inputSchema, annotations?, side: 'shell'|'app', risky }`); empty unless `principal` is the owner.
+- `authorizeCall(principal, name): Promise<CatalogTool>`: throws `PolicyError` (`status` 401 no principal, 403 not the owner or unknown tool).
+- `callTool(principal, name, args)`: authorize and run. A risky call returns a `PendingApproval`.
+- `Principal = { id, tenantId, scopes? }`; get one from the request with `principalFromLocals(locals)` (`owner.ts`).
+
+## The assistant
+
+The dock (`src/lib/assistant/AssistantDock.svelte`, mounted for the owner in
+the layout) talks to `mountAssistantRoutes` (`src/lib/server/assistant/`).
+Owner session required on all of them (401/403); the POST is same-origin.
+
+| Route | Body | Response |
+|---|---|---|
+| `GET /api/assistant/status` | | `{ configured: boolean, code?, message? }`; never a key, provider or endpoint. `code` is `assistant_not_configured` (no API key), `assistant_provider_refused` (subscription provider configured) or `ai_unavailable` (inference off) |
+| `GET /api/assistant/threads` | | `{ threads: { id, title, updatedAt }[] }` newest first |
+| `GET /api/assistant/threads/<id>` | | `{ thread, messages: ThreadMessage[] }`; 404 for a missing or foreign thread |
+| `POST /api/assistant/turn` | `{ message, threadId? }` | `text/event-stream`, `event: turn`, JSON `TurnEvent` (below). **503** `{ type: 'unavailable', configured: false, code, error }` when the assistant cannot run; 409 while another turn is running |
+
+`TurnEvent` (`src/lib/assistant/events.ts`): `thread {threadId}`, `text {delta}`,
+`tool_call {id,name,args}`, `tool_result {id,name,ok,summary}`,
+`approval_required {id,name,approvalId,summary,preview}`,
+`approval_decided {id,approvalId,status}`, `error {code,message}`,
+`done {stop}` (`complete | max_steps | max_tokens | timeout | aborted | waiting | error`).
+Closing the request (the dock's Stop button, a closed tab) aborts the model
+call, the running tool and any wait.
+
+- **Tools.** The model is offered `toolsFor(owner)` (builder tools plus the
+  app's generated tools); each call is checked against
+  a fresh list and then goes through `callTool` (the same policy as `/mcp`).
+  Non-owners get no tools and no assistant. Calls run one at a time, in order.
+- **Risky calls.** A risky call returns a `PendingApproval`; the turn emits
+  `approval_required` and is held (`holdForUser`) until the owner decides it
+  (the dock's card POSTs `/api/shell/approvals/<id>`, so it goes through
+  `Approval.decide`). The model is then told approved, denied or failed. If the
+  wait times out or the client leaves, the model is told it is waiting, the
+  turn ends as `waiting`/`aborted`, and the Approval stays pending, unapplied.
+  The assistant has no way to set the engine's `approved` flag.
+- **Engine.** `@happyvertical/ai` through core's inference tiers
+  (`resolveInferenceTarget`, tier `good`, override `SMRT_APP_SHELL_ASSISTANT_TIER`).
+  The key comes from the `ai` block of `smrt.config.ts`, `SMRT_AI_*` or the
+  provider's own variable (`ANTHROPIC_API_KEY`), read only server side, never
+  logged or sent to the browser, until bring-your-own (#4666) lands. Subscription
+  providers (`claude-cli`, `chatgpt-plan`) are refused. With no key,
+  status/turn answer the typed not-configured state and the dock shows it.
+- **Bounds** (`DEFAULT_LIMITS` in `turn.ts`): 8 model rounds, 2048 output
+  tokens per call, 60 000 tokens per turn, 4 calls per round, 60 s per model
+  call, 180 s of model/tool time per turn, 15 min per approval wait.
+- **Guidance.** `src/lib/assistant/guidance/system.md` (bundled with `?raw`).
+- **Threads** persist in shell.db (`assistant_threads`, `assistant_messages`).
+- **Tests** inject a stub model (`modelFactory` option, `test-helpers.ts`).
+
+## First-run schema
+
+`prepareShellSchema(db)` (`src/lib/server/schema.ts`) creates the tables of every
+registered shell model (and the smrt-users, tenancy and profiles tables the
+runtime needs) when missing, so an empty data directory boots without
+`DB_SCHEMA_MISSING`. It is passed to app-runtime's existing `prepareDatabase`
+option. Dependency: the first-run schema hook of smrt#4835 is pending; the
+shell will switch to it in `smrt.ts` when it lands.
+
+## Develop
+
+```
+pnpm --filter @happyvertical/smrt-app-shell test
+pnpm --filter @happyvertical/smrt-app-shell build
+pnpm --filter @happyvertical/smrt-app-shell typecheck
+```
+
+See [AGENTS.md](AGENTS.md) for the invariants and [agents/engine.md](agents/engine.md) for the engine.

package/agents/engine.md

@@ -0,0 +1,85 @@
+# App-shell engine (`src/engine`)
+
+Runs a person's own smrt app from a versioned JSON definition. The host
+(`AppHost`) owns the version history (through a `VersionStore`) and the data
+directory; the app itself runs in a worker thread with its own registry and
+`app.db`. Every definition change starts a fresh worker (the registry only
+adds) and swaps it in once it is ready. The engine must not import SvelteKit,
+`$lib`, or anything under `src/lib`.
+
+## Rules
+
+- **Approval gate.** `RISKY_COMMANDS`, `isRiskyCommand` and `isRiskyTool` live
+  in `commands.ts`. `execute` throws `ApprovalRequiredError` for a risky
+  command without `approved: true`; `callAppTool` does the same for
+  `<model>_delete`, and `rest` for `DELETE`. Approval covers the command, not a
+  plan hash: the plan is recomputed at execute time.
+- **Queue.** Work inside the change queue must call `callApp`, never `onApp`
+  (which awaits the queue): the old `clean_up` deadlock.
+- **Migrations** (`app-runtime.ts`) run in one transaction in the new worker,
+  reading through the transaction handle. Destructive ones retire the old worker
+  first and restart the old definition if the new one fails. They are
+  SQLite-shaped (`RENAME/DROP COLUMN`, `VACUUM INTO`, `pragma_table_info`);
+  Postgres is future work.
+- **Column storage.** No column-type history: re-adding a field checks the real
+  column's storage family. Text defaults can be `''`, so counts and archives use
+  `IS NOT NULL AND <> ''`. Renames do not rewrite method code; the plan lists
+  `affectedMethods`.
+- **App subclass rule.** `enableRecipe('profiles')` adds the app model
+  `Profile` (`extends` the shipped class). Its fields are nullable columns on
+  the shipped `profiles` table (STI). Never subclass `ProfileType` (its
+  subclass would get its own table). Creating a Profile find-or-creates the real
+  `person` `ProfileType`.
+- **Sandbox** (`sandbox.ts`): QuickJS, pure function over a copy of the data.
+  Everything crossing the boundary is JSON text. Limits: time, memory, a small
+  stack (128 KB), 1000 writes, 1 MB output, 8 MB input. The body is checked as a
+  function body by V8 first (QuickJS's own `Function` accepts a body that closes
+  the wrapper). Writes are validated and a `VACUUM INTO` snapshot is taken before
+  they are applied.
+  `setMemoryLimit` does not bound large single allocations in this build, and the
+  interrupt handler is polled only every ~10,000 operations, so the WebAssembly
+  heap itself is capped (`SANDBOX_HEAP_PAGES`, 128 MB): a memory bomb stops in
+  ~0.2 s instead of allocating 2 GB.
+
+## Profile subclass (core gap fixed, #4871)
+
+The app subclass of the shipped `Profile` is registered as
+`@local/app:Profile`, the same class name as its parent. Core keeps the two
+apart: `registerRuntimeModel` leaves a same-named parent registered (constructor
+index, no lineage replacement), and the parent's generated REST and MCP
+surfaces are closed with `ObjectRegistry.registerOverride(parent, { api: false,
+mcp: false })` in `AppRuntime.register`, so only the subclass's tools exist.
+Covered by core's `runtime-model.test.ts` and engine `profile-subclass.test.ts`.
+
+## Safety rules added in review
+
+- **Undo is gated when it overwrites data.** `undo` is not in `RISKY_COMMANDS`;
+  the host decides from the *stored* version (`analyseUndo`): a version with a
+  `convertColumn` step restores each row's archived original on the way back,
+  replacing values written since, so the plan is `risky` with a read-only
+  `countOverwrites` preview (`replaced`, `fields[]`). Every other undo stays
+  immediate. The shell pins the approval to that version (`undo.version`); the
+  host refuses if the app moved on.
+- **REST surface.** `restRouteAllowed` (definition.ts) lets only
+  `/api/<route>` and `/api/<route>/<id|action>` of the app's own models through,
+  in `AppHost.rest` and `AppRuntime.rest`. Core's reserved `sync/apply` (its
+  `delete` op deletes records), `_changes`/`_events`/`_inference` and the
+  registry fallback to shipped classes (e.g. `ProfileType`) are 404 before the
+  DELETE gate. `DELETE` on an allowed route still needs approval.
+- **Snapshot retention** (`snapshots.ts`): the worker keeps the newest 20
+  `method-*` snapshots after each new one; `cleanUp` removes `migrate-*` and
+  `schema-*` snapshots older than the newest change it purges. Only plain files
+  matching the engine's own name pattern in `snapshots/` are ever deleted
+  (never symlinks, directories or other files).
+- **importTemplate preview** lists every method (model, name, description,
+  params, code), so what the owner approves is what is shown; a template with
+  more than 200,000 characters of method code is refused as unreviewable.
+
+## Lessons
+
+- A worker must not be terminated while `@happyvertical/sql`'s startup HMAC key
+  job is pending (Node aborts the process); `app-worker.ts` settles it before
+  reporting ready.
+- If V8 overflows its own stack inside WebAssembly, QuickJS cannot recover; the
+  small QuickJS stack limit keeps its error first, and a host-level failure
+  discards the WASM module instance.

package/dist/engine/app-runtime.d.ts

@@ -0,0 +1,138 @@
+import { type AppDefinition, type FieldDef, type Migration, type Step } from './definition.ts';
+import { type MethodOutput, type Write } from './sandbox.ts';
+type Row = Record<string, unknown>;
+export interface BootResult {
+    statements: string[];
+    snapshot: string | null;
+}
+export declare class AppRuntime {
+    readonly def: AppDefinition;
+    readonly version: number;
+    private db;
+    private dataDir;
+    private snapshots;
+    constructor(dataDir: string, def: AppDefinition, version: number);
+    /**
+     * Open app.db, register the definition, and bring the tables up to it: the
+     * migration's steps (if any) and then the additive changes, all in one
+     * transaction. A failure leaves app.db exactly as it was.
+     */
+    boot(migration?: Migration): Promise<BootResult>;
+    /** Register the definition's models in this (fresh) registry. */
+    private register;
+    private qualified;
+    /**
+     * Statements that bring tables up to the registered models, reading
+     * through `h`. With `run`, each model's statements execute before the next
+     * is planned (the subclass of a shipped model plans against its parent's
+     * table). Shipped tables come first.
+     */
+    private plan;
+    private existingColumns;
+    /** A column that exists with another storage family than its field wants: refuse. */
+    private checkColumns;
+    private columnTypes;
+    private tableExists;
+    /** Run one step up or down inside the boot transaction; returns what it did. */
+    private runStep;
+    /** What a type change would do to existing values, without changing anything. */
+    previewConversion(table: string, key: string, column: string, to: FieldDef): Promise<{
+        rows: number;
+        withValue: number;
+        convertible: number;
+        failing: {
+            id: unknown;
+            value: unknown;
+        }[];
+        failingCount: number;
+    }>;
+    /** How many non-empty values a column holds (for a removal preview). */
+    countValues(table: string, column: string): Promise<number>;
+    countRows(table: string): Promise<number>;
+    /** How many archived values and tables the given versions hold. */
+    countArchives(versions: number[], tables: string[]): Promise<{
+        values: number;
+        tables: number;
+    }>;
+    /**
+     * How many rows undoing `version`'s `convertColumn` steps would overwrite:
+     * rows whose current value is not what converting the archived original
+     * gives (they were edited, or created over the original, since).
+     */
+    countOverwrites(version: number, steps: Step[]): Promise<{
+        table: string;
+        column: string;
+        replaced: number;
+    }[]>;
+    /** Delete archived values and tables for the given versions. */
+    purgeArchives(versions: number[], tables: string[]): Promise<{
+        values: number;
+        tables: number;
+    }>;
+    /** A consistent copy of app.db in snapshots/, made with VACUUM INTO. */
+    snapshot(kind: string): Promise<string>;
+    /** Delete migrate/schema snapshots taken before `beforeMs` (clean up). */
+    pruneSnapshots(beforeMs: number): number;
+    private mcp;
+    private toolNames;
+    /** The app's own generated MCP tools: chore_list, chore_complete, ... */
+    tools(): Promise<import("@happyvertical/smrt-core").MCPTool[]>;
+    callTool(name: string, args: Row): Promise<{
+        content: any;
+        isError: boolean;
+        structuredContent: any;
+    }>;
+    /** SMRT's generated REST routes. */
+    rest(req: {
+        method: string;
+        url: string;
+        body?: string;
+    }): Promise<{
+        status: number;
+        contentType: string;
+        body: string;
+    }>;
+    describe(): {
+        name: string;
+        version: number;
+        recipes: string[];
+        models: Record<string, import("./definition.ts").DescribedModel>;
+    };
+    private modelDef;
+    /** Fields a record of `model` carries: built-in ones and visible own ones. */
+    private fieldsOf;
+    private collection;
+    private plain;
+    list(model: string, limit?: number): Promise<Row[]>;
+    get(model: string, id: string): Promise<Row>;
+    /** Check and convert `data` for a write. `refs: false` skips target lookups (imports). */
+    private coerce;
+    create(model: string, data: Row, opts?: {
+        id?: string;
+        refs?: boolean;
+    }): Promise<Row>;
+    update(model: string, id: string, data: Row): Promise<Row>;
+    remove(model: string, id: string): Promise<{
+        deleted: string;
+    }>;
+    /** Create records of a template with their ids (references stay valid). */
+    importRecords(records: Record<string, Row[]>): Promise<{
+        records: number;
+    }>;
+    /** Find or create the real `person` ProfileType (the type of every app Profile). */
+    private personType;
+    runMethod(model: string, method: string, id: string | null, params?: Row): Promise<{
+        result: unknown;
+        writes: never[];
+        applied: number;
+        snapshot: null;
+    } | {
+        result: unknown;
+        writes: Write[];
+        applied: number;
+        snapshot: string;
+    }>;
+    /** Reads only: records exist, required fields are present, references resolve. */
+    private checkWrites;
+}
+export type { MethodOutput };