ihp-railiance-probe/SCOPE.md

# SCOPE

This file defines what `ihp-railiance-probe` owns, when to use it, and where
its boundaries stop.

Last reviewed: 2026-06-04

---

## One-liner

A minimal IHP-on-Railiance canary application that proves the full path from
Nix production build to Gitea OCI image, Helm deployment on Railiance01, and
live HTTP smoke verification.

---

## Core Idea

`ihp-railiance-probe` is intentionally small. It exists to make expensive
IHP/GHC/Nix/deployment failures cheap to reproduce before larger applications
such as `inter-hub` rely on the same path.

The repo owns a tiny IHP app, the production build shape, a Helm deployment
chart, and the evidence trail for end-to-end validation. Its value is not
business functionality; its value is proving that the IHP workload pipeline is
healthy enough for real apps to use.

---

## In Scope

- Minimal IHP application code:
  - `Web/Controller/Health.hs` for `GET /healthz -> ok`;
  - `Web/Controller/Probes.hs` for basic `probes` CRUD;
  - routes, views, schema, and fixtures needed for the small probe surface.
- Minimal database schema in `Application/Schema.sql`:
  - `uuid-ossp` extension;
  - one `probes` table with `id`, `name`, and `created_at`.
- Test-first validation surface:
  - `Test/ProbeControllerSpec.hs`;
  - `Test/Main.hs`;
  - Hspec checks for `/probes` and `/healthz`.
- IHP/Nix production build configuration:
  - `flake.nix`;
  - IHP v1.5 inputs;
  - `nix build .#docker`;
  - low-memory GHC runtime settings and the GHC 9.10.3 mitigation overlay.
- Kubernetes deployment artifact:
  - Helm chart under `chart/`;
  - deployment, service, ingress, image settings, resource limits, and
    `/healthz` liveness probe.
- Pipeline documentation and evidence:
  - `INTENT.md`;
  - `DeploymentBlueprint.md`;
  - `PIPELINE_LOG.md`;
  - completed workplan `workplans/IRP-WP-0001-pipeline-validation.md`.

---

## Out of Scope

- Production business functionality. This is a probe, not an application
  product.
- `inter-hub` source code, domain model, features, or release ownership.
- Generic IHP framework maintenance.
- Railiance OS provisioning, Kubernetes runtime setup, and shared platform
  services.
- Long-term ownership of Gitea, registries, PostgreSQL, ingress controllers, or
  k3s cluster configuration.
- Secret custody. The chart references an environment Secret name, but this
  repo must not store live secret values.
- A general-purpose application template. Lessons may inform templates
  elsewhere, but this repo stays a small validation target.

---

## Relevant When

- Validating that an IHP project can build a production OCI image with the
  current Nix/IHP/GHC stack.
- Checking whether known GHC 9.10.3 production-build mitigations still work.
- Proving the Gitea container registry push path for an IHP image.
- Testing that Railiance01 can pull and run the image from the Gitea registry.
- Verifying Helm deployment, service routing, ingress, and `/healthz` behavior
  for an IHP workload.
- Rehearsing the path before promoting a larger IHP app.

---

## Not Relevant When

- You need application features or user-facing product behavior.
- You need to debug the internals of `inter-hub`.
- You are provisioning hosts, installing k3s, or managing cluster-level addons.
- You are designing shared Railiance platform services such as databases,
  secret management, object storage, or caches.
- You need a durable production service with real data and recovery guarantees.
- You need canonical CI/CD or developer enablement templates rather than this
  specific probe implementation.

---

## Current State

- Status: validated canary.
- Implementation: minimal IHP app, schema, health endpoint, probe CRUD, tests,
  Nix Docker image build config, Helm chart, deployment blueprint, and pipeline
  log are present.
- Stability: suitable as a regression probe; intentionally narrow.
- Usage: two end-to-end pipeline runs are recorded in `PIPELINE_LOG.md`
  (`e372a0c` on 2026-05-03 and `511a503` on 2026-05-07), both with build,
  push, deploy, and smoke marked PASS.

The completed workplan records Gitea Actions automation as done, but the
repository surface visible here does not currently include a
`.gitea/workflows/` file. Treat that as a documentation/state gap to verify
before relying on unattended CI.

---

## How It Fits

- Upstream dependencies:
  IHP v1.5, GHC 9.10.3, Nix/devenv, haskelseed build host, Gitea OCI registry,
  Railiance01/k3s, Helm, and a PostgreSQL-compatible `DATABASE_URL`.
- Downstream consumers:
  humans and agents validating the IHP-on-Railiance release path; larger IHP
  applications that want confidence before promotion.
- Often used with:
  `inter-hub`, `railiance-apps`, `railiance-enablement`, Gitea on CoulombCore,
  and Railiance01.

---

## Terminology

- Preferred terms:
  probe, canary, pipeline validation, smoke test, IHP-on-Railiance.
- Also known as:
  IHP deployment probe, Railiance IHP canary.
- Potentially confusing terms:
  this repo is "upstream in confidence" from `inter-hub`, not a source-code
  dependency of it.

---

## Related / Overlapping Repositories

- `inter-hub` - the larger IHP workload whose expensive build/deployment
  failures motivated this small probe.
- `railiance-apps` - owns S5 application release patterns and app workload
  operations for Railiance; this repo is a source workload used to validate an
  IHP path into that layer.
- `railiance-enablement` - eventual home for reusable CI/CD, templates, and
  developer delivery paths that this probe may inform.
- `railiance-cluster` - owns Kubernetes runtime concerns such as k3s and
  cluster-level registry configuration.
- `railiance-platform` - owns shared stateful services such as databases and
  secrets consumed by workloads.

---

## Getting Oriented

1. Read `INTENT.md` to understand why the repo exists.
2. Read `DeploymentBlueprint.md` for the full workstation -> haskelseed ->
   Gitea registry -> Railiance01 flow.
3. Read `PIPELINE_LOG.md` for recorded successful pipeline runs.
4. Inspect `flake.nix` for the production image build and GHC mitigations.
5. Inspect `chart/` for Kubernetes deployment shape.
6. Inspect `Web/Controller/Health.hs`, `Web/Controller/Probes.hs`, and
   `Test/ProbeControllerSpec.hs` for the app and smoke-test surface.
7. Inspect `workplans/IRP-WP-0001-pipeline-validation.md` for the completed
   validation sequence and operational caveats.

---

## Provided Capabilities

```capability
type: validation
title: IHP-on-Railiance pipeline canary
description: Minimal IHP application used to validate Nix production builds, Gitea OCI registry push, Helm deployment on Railiance01, and live HTTP smoke checks before larger IHP workloads are promoted.
keywords: [ihp, railiance, probe, canary, nix, ghc, gitea, helm, kubernetes, smoke-test]
```

```capability
type: documentation
title: IHP deployment blueprint and evidence log
description: Documents the full IHP build-to-deploy path, known infrastructure constraints, and recorded end-to-end pipeline smoke evidence.
keywords: [deployment-blueprint, pipeline-log, haskelseed, railiance01, registry, evidence]
```

---

## Notes

The README still looks like the original seed template. Use `INTENT.md`,
`DeploymentBlueprint.md`, and this file as the current orientation documents.