Review and records

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)	`domains/<domain>/events/events.jadpo_record`	Yes	`jadpo records update`	`check`, reviewers
Access record	Who can do what: each entity's and field's grants, where records belong, the actions and queries listed separately, the security rules declined, the sign-in settings that have a limit and your company's own git locations (Acceptances)	`access.jadpo_record`	Yes	`jadpo records update`	`check`, reviewers
Network record	Every outside host the app can reach, by connection (The network report)	`network.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 fmt --layout`, and `jadpo rename` and `jadpo domain …`, not built yet	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/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 (External services)	`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)	`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`

Reviewing a change

When an agent hands you a change, you should see it in the order it matters.

Review and sign-off

The changes a person must accept before they ship, such as one that can break an API client or drop something from the database.

What is committed, and why

You commit a file only if it can't be worked out again from today's source, or if it is a promise whose diff a person must read.

Acceptances

Some changes can break someone else, such as removing a field clients read.

Comparing two builds

Every review is a diff of two manifests.

Package upgrades

An upgrade is a change to jadpo.lock and packages/, reviewed like any other change, its surface.jadpo_record diff included.

Examples: an API change, a package upgrade and an incident

The agent commits and opens the pull request, saying a reason is needed.

The manifest

jadpo check writes one manifest for your project, build/manifest.json, whether the project has errors or not.

Stable identity

Jadpo knows a declaration or field by the name it was born with, so a rename never looks like something removed and something added.

Production builds

A deployable carries a small build stamp, not its manifest.

What is built says which of this works today.

Related