# Jadpo

> Jadpo is an experimental programming language for web backends written by AI agents and reviewed by people. Its compiler checks who may see what, how data is stored and changed, and every call to an outside service.

## For agents

- Jadpo is new and changes between versions, so don't rely on what you remember about it. Read https://jadpo.dev/docs/primer.md before writing any Jadpo.
- Find pages in https://jadpo.dev/docs/index.json by title and summary, and fetch only the `.md` pages a task needs.
- To teach a person Jadpo, or build a first app with them, follow the Learn path below in order.
- A compiler error names a rule. Its page is https://jadpo.dev/docs/errors/<rule>.md.
- When an error's next step ends in (human), stop and ask your user before changing anything.
- Coding agents can install the Jadpo skill, which holds these instructions and more: https://jadpo.dev/.well-known/agent-skills/jadpo/SKILL.md.
- These are the newest docs, from Jadpo's main branch at version 0.1.0, and they may describe things a released Jadpo can't do yet. Each released minor version has its own docs. Run `jadpo version --json` for your version: for example, for 0.3.2, read https://jadpo.dev/v/0.3/llms.txt instead.

## Learn

- [Learn Jadpo](https://jadpo.dev/learn.md): This path builds one app, a todo list with sign-in, from an empty folder to a deployed server.
- [1. What Jadpo is, and setting up](https://jadpo.dev/learn/learn-setting-up.md): Jadpo is a programming language for web backends: the server side of an app, which keeps its data and answers its HTTP requests.
- [2. A project and your first route](https://jadpo.dev/learn/learn-first-route.md): On this page you start the todo app that the rest of this path builds, and get it answering its first HTTP request.
- [3. Types](https://jadpo.dev/learn/learn-types.md): On page 2 a todo's title was any `Text`, so the app took an empty title, or one a megabyte long.
- [4. Storing todos](https://jadpo.dev/learn/learn-storing.md): So far `add_todo` sends a todo back and forgets it.
- [5. Failures](https://jadpo.dev/learn/learn-failures.md): Some requests are well formed but still wrong: a todo due yesterday has a valid date, but no one can do it in time.
- [6. Reading todos](https://jadpo.dev/learn/learn-reading.md): The app stores todos but can't show them.
- [7. Changing and deleting todos](https://jadpo.dev/learn/learn-changing.md): This page adds the routes that change a todo: `PATCH /todos/{id}` edits its title or marks it done, and `DELETE /todos/{id}` removes it.
- [8. Tests](https://jadpo.dev/learn/learn-tests.md): You've been checking the app by hand with `curl`.
- [9. Settings](https://jadpo.dev/learn/learn-settings.md): Some values differ between your machine and the server the app runs on: the site's address, a mail server's password, a limit you want to tune without a release.
- [10. Users and the principal](https://jadpo.dev/learn/learn-users.md): Until now anyone could call every route, and a todo belonged to no one.
- [11. Signing in by email](https://jadpo.dev/learn/learn-sign-in.md): Page 10 gave the app users, but no way to sign in.
- [12. Who may see what](https://jadpo.dev/learn/learn-policy.md): Since page 10, any signed-in person can read and change anyone's todos.
- [13. Deploying to a server](https://jadpo.dev/learn/learn-server.md): `jadpo dev` runs the app with a throwaway database and catches every email.
- [14. Deploying to Cloudflare Workers](https://jadpo.dev/learn/learn-workers.md): Cloudflare Workers runs your code on Cloudflare's network, close to whoever calls it, with no server of your own to look after.

## Reference

- [Primer](https://jadpo.dev/docs/primer.md): Read this once before you write a Jadpo app.
- [Project layout and modules](https://jadpo.dev/docs/project-layout-and-modules.md): How a Jadpo project is laid out on disk, how one file sees declarations from another, and the naming rules every name follows.
- [Values and types](https://jadpo.dev/docs/values-and-types.md): What kinds of value a Jadpo program works with, how you give a value a meaning in your business, and when one type can stand in for another.
- [Logic](https://jadpo.dev/docs/logic.md): How you write what your app does: functions and actions, variables and constants, statements, operators, `match`, `attempt` and loops, and what Jadpo allows for passing functions, recursion and…
- [Failures](https://jadpo.dev/docs/failures.md): Your code says what went wrong, by name, and Jadpo decides how each failure reaches whoever called: the HTTP status, the response body and what is logged.
- [Data](https://jadpo.dev/docs/data.md): How you declare the records your app keeps, where they are stored, and how their shape changes over time.
- [Reads and writes](https://jadpo.dev/docs/reads-and-writes.md): How a program reads and changes stored records: named queries, filters, order and pages, totals, related records, the operations every entity gets, what a refused write reports, and how an action…
- [HTTP](https://jadpo.dev/docs/http.md): A Jadpo app answers HTTP requests with routes.
- [Identity](https://jadpo.dev/docs/identity.md): Identity is how Jadpo knows who is calling.
- [Policy](https://jadpo.dev/docs/policy.md): Policy says who may do what to which stored records.
- [Configuration and time](https://jadpo.dev/docs/configuration-and-time.md): This page covers the values your app reads from its environment, such as a database address or an API key, and everything to do with time: the current time, dates and time zones, and showing dates,…
- [External services](https://jadpo.dev/docs/external-services.md): An external service is another company's API, such as Stripe, a courier or another Jadpo app, that your actions call.
- [Jobs and events](https://jadpo.dev/docs/jobs-and-events.md): This page covers the work your app does outside a request: schedules that run an action on a timer, events an action announces, subscribers that react to them, and what happens when that work fails.
- [Testing](https://jadpo.dev/docs/testing.md): A Jadpo test runs your real application against a real database.
- [Tooling](https://jadpo.dev/docs/tooling.md): The `jadpo` command and everything around it: the formatter, the editor support, how errors are shown, the generated `build/` folder, the tools agents use to look things up before they change code,…
- [Personal data](https://jadpo.dev/docs/personal-data.md): Your app says which data is about a person, and Jadpo does the rest: it exports that data when the person asks for a copy, erases it when they ask to be forgotten, deletes it when its time is up, and…
- [Built-in services](https://jadpo.dev/docs/built-in-services.md): Jadpo gives your app some common backend features itself, so you don't install a library or write your own: feature flags, rate limits, files, an audit trail, telemetry, email, documents, search and…
- [Debugging and review](https://jadpo.dev/docs/debugging-and-review.md): Jadpo code is written mainly by coding agents and read by people, so two jobs matter most.
- [Records and manifest](https://jadpo.dev/docs/records-and-manifest.md): Besides your running app, the compiler writes two kinds of file, and it keeps them apart so that every change can be reviewed and every production event traced back to its source.
- [Standard library](https://jadpo.dev/docs/standard-library.md): The standard library is the set of types and operations every program can use without declaring them, such as `Money`, `list.count(items)` and `temporal.in_zone(at, zone)`.
- [Geospatial](https://jadpo.dev/docs/geospatial.md): Geospatial values say where things are, and what is near or inside what: a bakery's position, the patches it delivers to, the shops within five kilometres of a customer, the pins inside the map a…
- [AI](https://jadpo.dev/docs/ai.md): Your app can ask a language model for an answer, a stream of text or an embedding (a list of numbers that stands for a text's meaning).

## When Jadpo is wrong

If the compiler crashes, rejects code the docs say is valid or accepts code the docs say it refuses, or a docs page is wrong:

1. Read the error's page, https://jadpo.dev/docs/errors/<rule>.md, and the docs it links to, to rule out a mistake in the code.
2. Cut the problem down to a minimal reproduction: the smallest Jadpo project that still shows it.
3. Draft a bug report and give it to your user, or give them a prefilled link to Jadpo's bug report form: https://github.com/jadpo-dev/jadpo/issues/new?template=bug.yml&title=. Never file an issue or comment yourself, because a public issue is published under your user's name.
4. Leave out secrets, configuration values and any code outside the minimal reproduction.
5. After a crash, Jadpo writes a crash file to `~/.cache/jadpo/crashes/`. Show it to your user, and attach it only once they've read it and agreed.

A suspected security hole never goes in a public issue. Report it privately, as Jadpo's security policy says: https://github.com/jadpo-dev/jadpo/blob/main/SECURITY.md.

## Optional

- [Jadpo on GitHub](https://github.com/jadpo-dev/jadpo): the compiler, the language reference and the examples