How the surface and the publishing bar work

This is the detail behind The surface and Developing and publishing a package: what a package's surface record holds, how its version is worked out, and what jadpo package check and jadpo package show do.

• The surface's entries. In the record format's order: the package; for a provider, provider; each operation of a public resource; each function of a public library; each public type (type Name = Base), then each public failure; each folder in recipes/. Each public action follows the operations ("Package actions and recipes"); its public messages, message translations.<message> with their fields, follow the functions, and the package's entry has a locale line for each language it words (Packages' text in an app). A library itself has no entry: its functions do. Declarations without public, and test files, are left out.
• The package's entry. kind is provider when the package has provider.jadpo; licence is the Licence variant's name (mit), as protocol json_http and credential bearer are written; jadpo is the index's text; guide GUIDE.md when the package carries one; version when it is known (below), and left out of an own integration's surface.
• The provider's entry holds protocol, host live and host sandbox, runs image, port and each asks host, credential, and idempotency header and window.
• Facts written as Jadpo writes them. A type's own rules are fields sorted by name (max_length: 8); an object's fields are name: Type sorted by name, a field's own rules in braces after its type (Text { max_length: 4 }) and default after it; an enum's variants are variant facts sorted, a variant's fields indented under it; a function's signature is its parameters and result without its failures, each failure a fails line; an operation's request is its method and path, then input, output, output_at, changes, idempotent, fails, source (written or imported, with its documentation page) and confirmed when recordings/<resource>.<operation>.json exists. Names are written as the package writes them, bare.
• Where surfaces live. jadpo package check writes an installed package's, in its own repository, beside package.jadpo; in an app it is held by the package's digest, so jadpo check doesn't regenerate it and jadpo records doesn't list it (a newer Jadpo writing surfaces differently would otherwise fail every app on code it can't change). jadpo check writes each own integration's to build/providers/<name>/<version>/surface.jadpo_record.
• jadpo package check takes the package's folder, by default the one it runs in, which must hold package.jadpo. It copies the package into a scratch app as its own integration (the golden rule), so the curated packages' reserved names are allowed there, and shows every path relative to the package's folder. Its bar is a row per item, each passed, failed or not checked yet; the surface is written when the package compiles and its version is allowed, even while another item fails, so the surface diff is there to read.
• The version. A release is a git tag v<version> whose committed surface.jadpo_record names the package. With none, the first release is the major version the label names (v2 is 2.0.0, v0 is 0.1.0, a dated label such as v2024_06_20 1.0.0). When nothing in the package's folder changed since the newest release, its version is that release's. Otherwise the surface is compared with that release's, entry by entry: a removed entry, or an entry whose facts changed (a new fails, a field retyped or added, a variant added, a licence changed), breaks an app and is refused; only new entries, or a new jadpo or locale in the package's entry, is the next minor version; nothing but descriptions, files, sources and recordings is the next patch. A breaking change is a new package (Postcodes.v3), not a new number. Outside git, every check is a first release.
• The bar's tests are the package's own .test.jadpo files, run in the interpreter in the scratch app.
• type.standard_exists in a package is held to its public types only: a type the package keeps to itself is what it decodes the provider's shape into before a value leaves. The words are a package's: convert at the edge, in the package.
• jadpo package show finds a package by its folder's name (postcodes), its name in code (Postcodes) or with its version (Postcodes.v2), and a declaration by the name the app writes after the package's (uk.parse, UkPostcode, bookings.create). An installed package's version and source come from its lock line; the app's own integration's source is "the app's own". Lists cut a long line with …; the declaration's own screen and --json hold it whole.

Polls and capability mappings aren't in the surface yet, and settings, webhooks, polls and erasure aren't in the provider's entry yet. jadpo package new and publish aren't built yet: they say toolchain.not_built_yet.