The surface

A package's surface is everything it offers an app, in one file you can read. To see a package's surface, run jadpo package show <name>. The compiler works it out from the package's code and writes it to surface.jadpo_record, beside package.jadpo. It lists:

• the package's description, licence and version;
• every public type with its fields and constraints, and every failure with its kind and code;
• every public library's functions, with their signatures, failures and descriptions;
• every recipe;
• for a provider: its operations (wire and output types both); each public action with the operations it calls on each path, which of them change something and which failures can follow an effect; its hosts or container, credential scheme, settings and polls; and the capabilities it provides.

Read as a diff

The surface is plain text in the format of the public API record, not JSON. Like every .jadpo_record file, it starts with a line saying what wrote it (Records and manifest). Installed packages are committed, so every upgrade's pull request carries the surface diff, and a reviewer reads "removed bookings.cancel, new failure PostcodeNotServed" in plain text.

Every entry points at its file, such as types/booking.jadpo, so an agent reads the surface first and opens only what it needs. A file is named after what it declares, so the pointer never goes stale.

Generated, never written by hand

jadpo package check writes the surface. add, update and the registry refuse a surface that doesn't match the code. The surface of an app's own integration is generated into build/.

The surface is kept out of package.jadpo, which a person writes. The descriptions stay in the source as /// comments, where the author edits them.

jadpo package show

jadpo package show <name> prints the description, licence, version, kind and public surface. jadpo package show <name> <declaration> prints one operation, type or function with its description and file. --guide prints GUIDE.md, and --json gives tools and agents the same. It works for installed packages and the app's own integrations alike.

It decides the version

Publishing compares the new surface with the last release's, and refuses a breaking change without a new major version. A breaking change is a public name removed, a field retyped or a new failure. The upgrade plan diffs the same two files.

The surface is surface.jadpo_record (record surface 1): the package's entry (description, file, kind, version, licence, Jadpo version, guide), a provider's provider entry (protocol, hosts or container, credential scheme, idempotency key), each public resource's operations, each public library's functions, each public type and failure, and each recipe, every entry with its file. jadpo package show prints it, one declaration in full or the guide, for installed packages and the app's own integrations alike, and jadpo check writes each own integration's surface to build/providers/<name>/<version>/surface.jadpo_record. The postcodes library package's, as jadpo package check writes it:

text

// Generated by Jadpo from this package's code; update it with `jadpo package check`, never by hand.record surface 1package Postcodes.v2    /// UK postcodes: reading them as people write them.    file package.jadpo    kind library    version 2.0.0    licence mit    jadpo 1.0function uk.tidy    /// Reads a postcode in upper case.    file libraries/uk.jadpo    signature (entered: EnteredPostcode) -> UkPostcode    fails InvalidPostcodetype EnteredPostcode = Text    /// A postcode as someone typed it.    file types/entered_postcode.jadpo    max_length: 20type UkPostcode = Text    /// A UK postcode in standard form, such as "SW1A 1AA".    file types/uk_postcode.jadpo    max_length: 8    min_length: 5failure InvalidPostcode    /// The text isn't a UK postcode.    file failures/invalid_postcode.jadpo    kind invalid_value    code invalid_postcode

and jadpo package show in an app that installed it:

text

$ jadpo package show postcodesUK postcodes: reading them as people write them.  package   Postcodes.v2  kind      library  version   2.1.0  source    path ../postcodes  licence   mit  jadpo     1.0  folder    packages/postcodes/v2Functions  uk.tidy          (entered: EnteredPostcode) fails InvalidPostcode -> UkPost…Types  EnteredPostcode  Text { max_length: 20 }  UkPostcode       Text { min_length: 5, max_length: 8 }Failures  InvalidPostcode  invalid_value✓ Postcodes.v2  1 function · 2 types · 1 failure→ jadpo package show postcodes uk.tidy  shows one in full, with its file

add and update verify the surface at install (under "Installing safely"); the choices are in "How the surface and the publishing bar work" below.