How the package format is read

This is the detail behind The package format: exactly how Jadpo reads a package's folder, its names and the lock. Read it when you write a package by hand or a check refuses one.

• A package's name is its folder's. packages/acme_couriers/v1/ is AcmeCouriers.v1: the folder's name in UpperCamelCase and its version folder, which the index has to give (package.name_mismatch). A version label is v and digits in groups joined by single underscores, v2 or v2024_06_20; the lock sorts the groups as numbers.
• What a package's code sees. Only its own declarations, bare, and the built-ins: not the app's shared/, domains, connections or other packages, since an installed package is published apart from any app and the app's own integration is written so that it could be. Its files need no use lines. It doesn't read the app's shared/; whether it should is an open question in the design notes, and allowing it later breaks no package.
• Bringing a package in. use packages/<name> for an installed one and use shared/providers/<name> for the app's own bring the whole package in, as use <domain> does; there is no { ... } form, since its names are always written through it. jadpo fmt sorts these lines after the domains'.
• Names through a package. A type (Postcodes.UkPostcode), a failure (fails Postcodes.InvalidPostcode), a type built from a value (Postcodes.UkPostcode(text)) and a public library's function (Postcodes.uk.parse(text)) are all written through the package's name.
• Its failures. A package's failure is known through its package in every fails list and outcome, and its code is the package's, not the app's: it isn't checked against the app's failure codes.
• The index. A /// description is required, as are licence: and jadpo:; jadpo: is a major and minor number as text, compared with nothing until Jadpo has a language version to compare it with. Licence.proprietary is refused for an installed package whose lock line isn't a git source; the app's own integrations may use it.
• provider.jadpo. Its top-level keys are checked, with hosts:' (live:, sandbox:), idempotency:'s (with window: required) and runs:'s keys; the others' values are read where they are used. protocol: is required, and hosts: with runs: is package.provider_invalid.
• The kind. A package with resources/ needs provider.jadpo (package.provider_missing); a provider package carrying translations/ is package.provider_translations.
• The digest. sha256: and the SHA-256 of one line per file, <the SHA-256 of its bytes> <its path>, paths relative to the package's folder in byte order, as Go's dirhash does; every file in the folder counts, hidden ones left out, so a changed, added or removed file is package.digest_mismatch.
• What isn't compiled. An installed package's tests (run when it is published, not in the app's jadpo test), its recipes/ and sample/ are read only for its digest. The app's own integration's tests run with the app's.
• Reserved names. Stripe, Twilio and GitHub, the curated packages this page names, compared by folder without underscores; only the app's own integration is refused one.
• A name the app uses. A package's folder name may not be a domain's or a library's, its name in code may not be a declaration's, and an installed package and the app's own integration never share a name (package.name_taken).
• The lock. jadpo check reads jadpo.lock and the committed folders only: each installed package needs its line (package.not_locked), each line other than a link its package (package.not_installed). A link line names a checkout, which every check compiles in the installed folder's place ("How packages are installed and linked").

Capability mappings other than receiving's and email's aren't built yet: one is toolchain.not_built_yet where it is declared.