L02 delivery catalog

Lesson 00 mapped the current delivery paths. Lesson 01 named the pipeline anatomy. This lesson turns those observations into a delivery catalog: a small inventory that makes large repos and multirepos understandable by declaring who owns a repo or service, how it builds, how it is tested, what artifact it produces, which environments it can reach, what triggers deployment, where secrets are allowed to appear, and which smoke checks prove runtime behavior.

This is a teaching artifact, not a platform build. The checked-in tutorial/delivery-platform/delivery-catalog.snapshot.json file is a small snapshot used for the exercise and for a cheap schema smoke test. It is not a live source of truth, and it does not require fos-workbench to build a service catalog product.

Why a catalog helps

When a repo is small, the delivery story can live in one person’s head. In a large repo or multirepo setup, that stops working. A platform team, repo owner, or future agent needs a compact answer to the same questions every time:

• ownership: who answers for this repo or service;
• build command: how source turns into deployable output;
• test command: how the repo proves a change is safe before promotion;
• artifact: what crosses the boundary between validation and deployment;
• environments: where the artifact can run or publish;
• deploy trigger: what event starts promotion;
• secrets boundary: where credentials appear and where they must not appear;
• smoke checks: what runtime behavior proves deployment worked.

The catalog is the delivery-platform equivalent of a map legend. It does not replace workflow YAML. It gives every workflow a common vocabulary.

The four contracts

A useful delivery catalog distinguishes four contracts.

Contract	Question it answers	Typical catalog fields
Repo contract	What does this repo or service own, and how does source become trusted?	Owner, scope, build command, test command, branch or path rules.
Artifact contract	What output is passed from validation into deployment or publication?	Bundle, image, generated reference, data artifact, static site build, version or retention rule.
Environment contract	Where can the artifact go, and what gate protects that place?	Local, staging, production, public docs, approval gate, environment URL.
Verification contract	What evidence proves the repo, artifact, and environment are healthy?	CI checks, drift checks, smoke checks, authorization checks, post-deploy feedback.

The secrets boundary cuts across those contracts. A polished platform should make it obvious that credentials are not part of the repo contract. They are runtime authority granted to a deployment job only after the relevant gates allow promotion.

Worked catalog snapshot

Snapshot caveat: the table below is a teaching snapshot, not a live inventory. fos-workbench is the repo this tutorial owns. The sibling fos values are included as a worked multirepo example, but they are caveated because this repo does not own or test the sibling source tree.

Field	fos-workbench	Sibling fos
Ownership	Repo owner / lab maintainer owns the tutorial/docs delivery path.	Sibling app owner / repo owner owns the outliner app delivery path.
Repo contract	Lessons, docs-site content, generated reference inputs, tests, workflow definitions, and delivery-platform guardrails live here. Azure files are validation-only historical context.	Outliner application source and app release workflows live in the sibling repo; this lesson records the shape as a snapshot.
Build command	npm run typecheck; before public docs changes, corepack pnpm --filter docs-site build.	Build the SvelteKit outliner application for Cloudflare Pages deployment.
Test command	npm run test from the root, including docs-site tests for content and navigation.	Svelte typecheck, unit tests, and advisory high-severity npm audit in the app CI path.
Artifact contract	Generated OpenAPI/dbt references, evaluation snapshot, serving DuckDB/Parquet substrate, Astro docs bundle, and Observable analyst-dashboards bundle.	SvelteKit build output deployed by Wrangler to Cloudflare Pages.
Environment contract	Public Cloudflare Pages docs site at dataplatform.kodeklaus.dk, including /dashboard/.	Cloudflare Pages staging at fos-app-staging.pages.dev and production at fhest.dk, with production protected by the GitHub production environment.
Deploy trigger	Push to main after the editor and serving CI jobs pass; deploy-docs publishes the docs surface.	Push to main affecting apps/outliner deploys staging; v* tag push or manual dispatch requests production release.
Secrets boundary	Cloudflare account and API token secrets are supplied only to the deploy-docs job at runtime.	Cloudflare Pages credentials and production approval live in the sibling repo configuration, not in fos-workbench.
Verification contract	Typecheck/test, generated-reference drift checks, Evalite, dbt, pytest, Dagster validation, streaming marker e2e, docs build, and post-deploy analytical-surface route checks.	Pull-request build/typecheck/unit-test feedback, staging deployment checks, production approval, and release smoke checks.
Smoke checks	Public analytical-surface routes respond after Cloudflare Pages deploy.	Staging checks login reachability and private workspace API auth failure; production checks Better Auth provider and private API authorization boundaries.

The row shape is more important than the exact formatting. A catalog entry should be short enough to scan and specific enough to tell a new contributor where ownership, artifacts, environments, and verification begin and end.

Exercise: classify a new repo or service

Pick a repo or service that is not in the snapshot. It can be a future recommendation API, a batch feature job, a docs-only repo, or a small internal tool. Add one draft row using the same catalog shape.

Use these prompts:

1. What is the repo contract? Name the owner, the source boundary, and the build and test commands a pull request must satisfy.
2. What is the artifact contract? Name the deployable or publishable output, and say whether it is a bundle, image, generated reference, data artifact, or something else.
3. What is the environment contract? Name the target environments and the gate that protects each one.
4. What is the verification contract? Name the CI checks and the smoke checks. If there is no smoke check, write the behavior you would expect one to prove.
5. Where is the secrets boundary? State which job may receive credentials and which parts of the repo must never contain them.

Then ask whether the row is operationally useful. If a new person can answer “who owns it?”, “what gets built?”, “where does it go?”, and “how do we know it worked?”, the catalog entry is doing its job.

How a polished platform would use it

A polished delivery platform would treat this catalog as input for self-service CI/CD. It could use the repo contract to suggest standard build and test jobs, the artifact contract to select publishing or image-retention rules, the environment contract to show allowed promotion targets, the secrets boundary to request the right credentials, and the verification contract to require smoke checks before calling a deployment complete.

This lesson is not building that platform now. For this module, the catalog is enough if it teaches the shape. Automation can come later only when repeated catalog rows reveal a stable need.

Checkpoint questions

1. In the worked snapshot, which fields belong mostly to the repo contract, and which fields belong mostly to the artifact contract?
2. Why is the sibling fos row marked as a snapshot caveat instead of a live catalog source owned by fos-workbench?
3. A new service builds a Docker image, deploys to staging on main, and deploys production only after manual approval. Which catalog fields should mention those facts?
4. A workflow has good unit tests but no post-deploy check. Which contract is incomplete, and what smoke check would you add?
5. Why would a self-service CI/CD platform need the secrets boundary before it offered a one-click deploy button?