# Records and manifest

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.

- A **record** is a promise to the outside world: your public API, the
  history of your database, the packages you pinned, and decisions people
  made. You commit records, review them as diffs, and each is changed by
  one command.
- A **build output** is a fact about one build. It is written again on
  every build and never committed. The main one is the **manifest**, the
  compiler's graph of your application. Every report is a view of it.

Reviewing a change means comparing two manifests. Explaining a
production event means rebuilding the manifest of the build that raised
it.

| Name | Holds | Where | Committed | Written by | Read by |
|---|---|---|---|---|---|
| API record | Each API's routes, fields and failure codes | `api/<api>.jadpo_record` | Yes | `jadpo api update` | `check`, reviewers, client teams |
| Event record | Each domain's events, the fields they carry and the types those name ([The event record](declaring-an-event.md#the-event-record)) | `domains/<domain>/events/events.jadpo_record` | Yes | `jadpo records update` | `check`, reviewers |
| Migrations | Each step of the database, with a snapshot of the whole schema | `database/migrations/` | Yes | `jadpo migrate new` | `migrate apply`, `check` |
| Identity registry | What each renamed thing was born as | `database/identities.jadpo_record` | Yes | `jadpo rename`, `jadpo domain …`, `jadpo fmt --layout` | the compiler, `migrate`, `incident` |
| Translation sources | For each locale and message, a hash of the default wording it was translated from, and each acceptance ([Translations as messages](translations-as-messages.md)) | `translations/sources.jadpo_record` in each translations folder | Yes | `jadpo translations update`, `import`, `accept` | `check`, `translations missing`, `approval` |
| Package surface | An installed package's public surface, each entry pointing at its file ([Integrations](external-services.md)) | `packages/<name>/<version>/surface.jadpo_record` | Yes, with the package | `jadpo package check`; verified by `jadpo package add` and `update` | `check`, `package show`, reviewers, the registry |
| Lock | Each installed package's version, digest and source: `registry`, `git` (repository, tag and commit), `path` or `link`; and the Jadpo release the project runs with, when it is pinned | `jadpo.lock` | Yes | `jadpo package add`, `update`, `remove`, `link`, `unlink`; `jadpo toolchain pin`, `unpin` | `check`, `build`, and every command, to choose the Jadpo that runs it |
| Suggestions kept quiet and taught | The suggestions a team ignored, and the patterns it taught `jadpo suggest` ([Suggestions](suggestions.md)) | `ignored_suggestions.jadpo_record`, `taught_suggestions.jadpo_record` | Yes | `jadpo suggest ignore`, `jadpo suggest found` | `suggest` |
| Acceptances | A person's decision to allow listed changes | `acceptances/` | Yes | drafted by `jadpo acceptance new`; the reason by a person | `check`, `approval` |
| Manifest | The application graph: every node with its source place, edges, routes, schedules, hosts, policy, thresholds | `build/manifest.json` | No | `check` | every report, `approval`, `incident`, `inspect`, console, MCP |
| Reports | Views of the manifest: permissions, personal data, network, database, queries, catalogues, OpenAPI, monitoring rules | `build/report/`, `build/catalogue/`, `build/openapi/`, `build/monitoring/` | No | `check` | people, agents, monitoring tools |
| Review | The difference between two manifests, decisions first | `build/review/` | No | `jadpo approval` | reviewers, CI |
| Build stamp | Build id, commit, compiler, deployable, target | Inside each deployable; on every log event | No | `jadpo build` | logs, `incident` |