App source and package

The Source App contract is deliberately small: one manifest, one final schema, one Actions entrypoint, one View entrypoint, optional JSON resources and conventional forward migrations.

Source tree

apps/<id>/
├── app.json                 required
├── schema.sql               required
├── actions.js               required
├── view.js                  required
├── assets/                  optional, JSON only
│   └── catalog.json
└── migrations/              optional
    ├── 2.sql
    └── 3.sql

Package contents

app.json
schema.sql
actions.js
view.js
assets/...                  only files declared by app.json
migrations/N.sql
credentials.json           optional first-install transport input

A .pocketapp is an uncompressed tar container capped at 2 MiB. The Installer accepts regular files only, rejects duplicate or unexpected paths, and stripscredentials.json before activation.

Execution order on a fresh install

1. Parse and validate app.json.
2. Create the App data root and initialize SQLite with schema.sql.
3. Evaluate the platform-owned System Framework inside a candidate Action Guest.
4. Evaluate actions.js and verify every declared Tool/schedule Action exists.
5. Evaluate the shared View SDK and view.js through a read-only database mount.
6. Store credentials natively, move source to apps/<id>/release, then register Tools and schedules.

What the runtime supplies

Your package does not carry:

• system/framework.js, which installs the PocketPi.* API;
• system/view-sdk.js and its packed font/resources;
• plan.json, native capabilities or platform modules;
• a QuickJS engine or PocketJS runtime binary.

Those belong to PocketPi and firmware. frameworkApi is the compatibility check between an App release and that platform-owned layer.

What is not supported

• multi-file ES module imports for executable App source;
• package.json, npm dependencies or a dependency graph;
• on-device TypeScript, TSX or JSX transformation;
• arbitrary binary assets or executable code under assets/;
• App-supplied native modules or a second JavaScript runtime.

Keep the current contract small until a concrete App cannot be expressed cleanly with one Actions entrypoint and one View entrypoint. Do not recreate a package ecosystem inside each App.