Understand generated files

View as Markdown

Registry Relay derives two kinds of output from one authored project: review material for the people who approve the contract, and a sealed package for the operator who runs it. Both are derived from authored intent. Neither is a second place to configure the service.

Keep one source of truth

Edit registry.yaml and the governance records, codelists, semantic profiles, and fixtures it references, then rerun the command that owns the output. A generated file that disagrees with the contract is a stale run, not a correction. Editing one changes nothing that Relay serves: the runtime rebuilds the same material from the contract at startup and refuses a package whose derived bytes differ.

Review output

relayctl generate writes into generated/ inside the project unless --output names another directory. It refuses a destination that already holds content, so a generated tree is always the product of exactly one run.

Path	What it carries
`SHA256SUMS`	The digest of every other file, one line per file, sorted by path
`REVISION`	The optional operator label given with `--revision`; absent without it
`registry.yaml`	The contract exactly as authored
`governed/`	Every governance file the contract references, plus the classification review rationale and its accepted identification report
`compiled/registry.json`	The canonical compiled Registry
`generated/`	The artifact set

The package’s generated/ directory holds the artifact set only. The review reports and the review starter stay in the authoring project: they are inputs to approval, not deployment material.

A package carries no database, no runtime.yaml, no secret, and no fixture. The operator supplies those at the deployment. Packaging refuses oversized input instead of truncating it: at most 256 referenced governance files totalling 16 MiB, and 1024 package files totalling 64 MiB.

What the package digest proves

The package digest is the SHA-256 digest of SHA256SUMS, so it covers every file’s bytes and the exact file set. relayctl package reports it, relayctl package --dry-run reports it without writing, and package.expectedDigest in runtime.yaml pins it. It detects a modified, truncated, or reassembled package. It is not a signature, and anyone who alters a package can recompute it, so authenticity stays a property of how the institution transfers, stores, and restricts the directory.

Acceptance does not stop at the digest. Loading a package refuses a changed, missing, or extra file by name, re-reads every file against its listed digest, recompiles the Registry from the governed files under the production profile, regenerates the whole artifact set, and requires byte-for-byte equality before the service opens a listener.

Visibility is derived, not stored

Relay derives whether each artifact is public, operation-bound, or operator-only from the compiled Registry at startup; the package stores no visibility of its own. relayctl package reports the derived exposure of every artifact so a reviewer can compare it across revisions. The split is plain in the two OpenAPI documents: openapi.public.json is what Relay returns from /openapi.json, while openapi.full.yaml describes every compiled operation, including the ones no anonymous caller can reach.