# How the registry commands work

This is the detail behind [Installing and updating from the
registry](/docs/the-public-registry.md#installing-and-updating-from-the-registry), [Yanks, takedowns and
advisories](/docs/the-public-registry.md#yanks-takedowns-and-advisories), [Search](/docs/the-public-registry.md#search) and
[Developing for the registry](/docs/the-public-registry.md#developing-for-the-registry): what each
command does and shows. The registry is `https://jadpo.dev/registry/v1/`;
`JADPO_REGISTRY` names a stand-in, over HTTPS or on this machine.

> **`add` and `update` take a release in this order**, and stop at the first
> that fails (`install.not_proved`), leaving the lock and `packages/` as they
> were: the release's details; the log's head, which has to extend the last
> one kept in `.jadpo/registry_head`, by `log/consistency`; `log/proof` at
> that head; the head kept; the archive, whose files have to have the digest
> the log holds; then the checks for a package from anywhere, compiling it
> and comparing its surface with its code; and lastly that the files are what
> the registry said: its name in code, its publisher (the scope of the name
> asked for), its version, its digest and the surface it shows. The facts on the screen are worked out from those files,
> not taken from the registry.
>
> ```text
> $ jadpo package add @acme/postcodes
> ✓ Added Postcodes.v2 2.1.0
>     folder     packages/postcodes/v2
>     source     registry @acme/postcodes
>     publisher  @acme, verified
>     age        first released 2026-08-14, 81 days ago
>     log        entry 412 of 1024
>     surface    matches its code
>
> Facts
>   kind      library, pure
>   storable  OutwardCode, UkPostcode, WrittenPostcode
>   failures  uk.tidy: InvalidPostcode
>
> ✓ package added  Postcodes.v2 2.1.0 · 1 function · 3 types · 1 failure
>
> → jadpo package show postcodes  shows what it offers
> ```
>
> The lock's line is `package Postcodes.v2 version 2.1.0 registry
> @acme/postcodes digest sha256:…`. A yanked release is `install.yanked`, even
> named with `--to`; a pre-release is taken only when named.
>
> **`update`** chooses among the installed major version's releases that
> aren't yanked or pre-releases: the newest at least three days old or marked
> urgent. A time that can't be read, or one still to come, is never old enough.
> It never goes down, and a new major is named and left, since it is a new
> package beside the old (`jadpo package add`). What it leaves is listed:
>
> ```text
> $ jadpo package update postcodes
> Newer, not taken
>   2.2.0  1 day old, taken from 2026-11-05
>   3.0.0  a new major, added beside this one with `jadpo package add`
>
> ✓ Postcodes.v2 is up to date  2.1.0 · registry @acme/postcodes · 2 newer
>
> → jadpo package update postcodes --to 2.2.0  takes it now, after showing its facts
> ```
>
> When it takes one, it shows when that was released, the facts, a new
> publisher, the surface's changes and every change record entry since the
> installed version. An urgent release says why, from the advisory against
> what is installed:
>
> ```text
> $ jadpo package update postcodes
> ✓ Updated Postcodes.v2 from 2.0.0 to 2.0.1
>     folder    packages/postcodes/v2
>     source    registry @acme/postcodes
>     released  2026-11-03, today
>     urgent    ADV-7: Reads the wrong outward code.
>     surface   matches its code
>
> Facts
>   kind      library, pure
>   storable  UkPostcode, WrittenPostcode
>   failures  uk.tidy: InvalidPostcode
>
> Change record, 2.0.0 to 2.0.1
>   ~ behaviour changed  uk.parse  a fix: it read the wrong outward code
>
> ✓ package updated  Postcodes.v2 2.0.1
>
> → jadpo check  checks the app against 2.0.1
> ```
>
> **`search <words>`** sends the words, and `--kind`. `--from` and `--to` read
> a standard type as it is, or a type of the app in this folder, whose shape is
> what goes: `Text { max_length: 12 }`, never a name or source of the app's.
> Results keep the registry's order, the standard library's first:
>
> ```text
> $ jadpo package search uk postcode
> Standard library
>   text.upper                Its account mentions postcode.
>
> Packages
>   @acme/postcodes uk.parse  Its account mentions uk, postcode.
>
> ✓ 2 found  1 in the standard library · 1 in a package
>
> → jadpo package add @acme/postcodes  installs the first package found
> ```
>
> **`audit`** asks about the lock's `registry` lines and sends nothing when
> there are none, and the others are counted as not checked. A declaration is
> reached when the graph's calls, uses and raises lead to it from anything of
> the app's own, tests left out. An app with errors has holes in its graph, so
> every advisory against it counts as reached.
>
> ```text
> $ jadpo package audit
> error: `Postcodes.uk.parse` has an advisory: ADV-7
>   reason: Reads the wrong outward code. It is against 2.0.0 to 2.1.2, and the app has 2.0.0 and reaches it.
>   next: Run `jadpo package update postcodes`, or give `--to` a release that fixes it (human)
>   rule: package.advisory
>
> Not reached
>   ADV-9  Postcodes.OutwardCode, 2.0.0 to 2.1.2: Too short for some codes.
>
> ✗ advisories the app reaches  1 reached · 1 not reached · 1 package
>
> → jadpo package update postcodes  takes a release that fixes it
> ```
>
> **`publish [--dry-run]`** runs in the package's own repository, with the
> package at its root. The tag is `v` and the version its committed surface
> says, and the repository is `origin`'s address, an ssh one as the same
> repository's `https://` address. It stops with `publish.not_at_tag` unless
> the checkout is that tag's commit, unchanged, and `origin` has the tag at the
> same commit, then runs the bar as `verify` does against the tag before, then
> asks the registry and waits up to 20 minutes for its verifier. A dry run
> passes in any state but `failed` or `cancelled`, and nothing it does is
> published. A package with no publisher stops at the bar, having asked
> nothing (`publish.publisher_missing`). A failed `publisher` row, or facts
> naming another publisher than the checkout does, is
> `publish.publisher_mismatch` rather than `publish.failed`.
>
> ```text
> $ jadpo package publish
> ✓ Asked the registry to release Postcodes.v2 2.1.0
>     publisher   @acme
>     repository  https://github.com/acme/postcodes
>     tag         v2.1.0
>     state       pending
>
> Registry's bar
> ✓ compiles  no errors
> ✓ tests     3 tests
>
> ● release pending  Postcodes.v2 2.1.0 · a releaser confirms it with a passkey on jadpo.dev
> ```
>
> **`preview [<folder>]`** serves one read-only page on this machine, on a port
> the system picks, until it is stopped: the verdict, its facts, its changes
> since the last tag, the publishing bar, its surface, changelog and guide, by
> the same run of the bar as `verify`, which writes nothing. It runs the bar
> again only when the package's files have changed. What only the registry can
> add, the written account, whether its publisher is verified, the Jadpo releases it works with and
> the last contract run, is named and not imitated.
>
> ```text
> $ jadpo package preview
> jadpo package preview  Postcodes.v2 · nothing is published · ctrl-c stops it
>
>   page  http://127.0.0.1:50321/
> ```