How a registry works

If you are deciding whether Base Registry Engine (BReg) can hold your institution’s registry, four questions settle most of it: what you define, what exists once the registry runs, who owns the result, and how you inspect it or recover when a change goes wrong.

What do I define?

You define a project: YAML files you keep in version control. It declares three things.

• Record types. The kinds of thing the registry holds, such as a facility or a licensed practitioner, with their fields, bounds, references to other Record types, and the routes that read and write them.
• Actions. Named operations with typed inputs and a plan of effects. A plan is either written out as fixed effects or computed by a small function, and it can only write the fields its Action declares.
• Access profiles. Who may do what: which token claims a caller needs, which operations and fields a profile grants, and which rows it reaches, for example only facilities in the caller’s jurisdiction.

BReg has no built-in domain. A facility exists because a project declares the Record type facility, not because the engine knows what a facility is. From the project, bregctl compiles the database schema, the HTTP routes, an OpenAPI document, and the metadata a client reads, all from the same source, so they cannot disagree.

What exists at runtime?

Once a project is packaged and activated, breg serves it from a PostgreSQL database the registry owns. Four kinds of thing accumulate.

• Records. One per facility, practitioner, or person. Every write keeps the earlier revision, so you can read what a Record said before it changed.
• ActionReceipts. When an immediate Action runs, every effect commits in one transaction and the caller gets an ActionReceipt listing what changed.
• Proposals. An Action in proposal mode does not change anything when it starts. It saves a draft; submitting freezes the exact inputs, target revisions, and effects. An outside review authority may approve or reject it, and the registry then applies that frozen plan, either automatically or when someone with the separate apply grant asks. The registry never reruns changed code to reinterpret a submission.
• The audit journal. Every request the registry admits is recorded, in a file or log stream kept apart from the database. Ship it to append-only storage and it becomes evidence nobody can quietly edit.

The facility template shows the three ways a change reaches a Record. Operators are created and patched through ordinary routes. register-facility is an immediate Action that creates a facility and its operator assignment together. A facility’s address can only change through a Proposal: correct-address is reviewed in Casework and applied automatically, and deactivate-facility needs no review but waits for someone allowed to apply it. A review approval alone never changes a Record; only applying the Proposal does.

Who owns the result?

Your institution does. The Records live in a database you run, under a project you wrote and review. Your OpenID Connect provider issues the tokens; BReg verifies them and issues none.

The registry refuses whatever the project does not allow. A caller whose profile does not grant an operation, a field, or a row gets the same answer as for something that does not exist, so a refusal does not reveal what is there. If a Record type says a change requires a Proposal, no immediate Action and no profile grant can skip it. And nothing outside the project changes a Record: every write arrives through a route, an Action, or a Proposal the project declares, under a profile that grants it.

Other products keep their own authority. A review in Casework decides; BReg applies. An Evidence assertion or a webhook delivery grants nothing in the registry.

How do I inspect or recover it?

Before anything runs, bregctl explain reads the project and prints what it compiles to: the model, who may do what, the routes, and each Action with its inputs, effects, commit checks, and the profiles that may start, review, or apply it.

Once a registry is deployed, bregctl status reports which package is active and the history of activations the database records, and bregctl doctor checks that the database, token issuer, and other dependencies the registry needs are reachable, without starting it.

When a change fails or its outcome is unknown, the record of what happened is the way back. Resending an immediate Action with the same Idempotency-Key returns the original ActionReceipt instead of running it twice. A Proposal carries links to the steps the caller may take next, such as retry, revise, or cancel, and says why one is unavailable. Revising opens a new draft and leaves the frozen earlier submission as it was. Record revisions show what each Record looked like before every write.

Next

• Author a registry project