# How the surface and the publishing bar work

This is the detail behind [The surface](the-surface.md) and
[Developing and publishing a package](developing-and-publishing-a-package.md):
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](packages-text-in-an-app.md)).
  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`.