# How the package format is read

This is the detail behind [The package format](the-package-format.md):
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.