blueprint-platform/docs/consumption/demo-runtime-source-of-truth.md

Demo Runtime Source Of Truth

Purpose

This document defines which system is authoritative for demo runtime behavior, how repo docs relate to deployed state, and how to validate or change that state safely.

The goal is to remove ambiguity between:

• Portainer stack definitions
• VPS Caddy site files
• Vault runtime and bootstrap material
• repo-owned runbooks and planning documents

Ownership Model

The source-of-truth model is split by concern.

Concern	Canonical Source	Live Materialization	Validation Path
Wave intent and execution order	plan/2026-03-27-s39-master-spa-depth-and-ops-hardening.md	N/A	Confirm task graph and plan links
Demo routing contract	docs/consumption/demo-auth-routing-runbook.md	Caddy site files on VPS	Validate hosts, path routing, and auth flow behavior
Demo container composition	Portainer stack definitions for demo stacks	Running Docker containers on VPS	Validate stack config against docs and deployed services
Secret operations and recovery	general_information/Vault.md	Vault host paths and core-vault container	Validate unseal, health, and expected secret paths
Registry endpoints and publication targets	general_information/Gitea.md	Gitea package and registry services	Validate package/image endpoints and login/pull paths
Cross-repo dependency safety	docs/architecture/workspace-cross-repo-reference-guard.md	.csproj graph in workspace	Run tools/validate-no-cross-repo-projectrefs.sh

Canonical Interpretation Rules

Use the following rules when repo docs and runtime state disagree:

1. Planning files define intended execution order and scope.
2. Repo runbooks define the expected runtime contract for routing, validation, and operational ownership.
3. Portainer and Caddy define the actual deployed runtime and must be reconciled back to the repo runbooks.
4. Vault operational recovery steps remain owned by general_information/Vault.md until a repo-owned ops runbook replaces them.
5. Gitea publication endpoints remain owned by general_information/Gitea.md until a repo-owned publication runbook replaces them.

This means:

• repo docs are canonical for expected behavior
• deployed systems are authoritative for current runtime
• any mismatch must be documented and reconciled, not silently accepted

Required Change Order

When changing demo runtime behavior, use this order:

1. Update the relevant repo docs first.
2. Apply runtime changes in the owning platform:
   • Portainer for demo stacks
   • Caddy for ingress and host routing
   • Vault for runtime secret operations
3. Validate deployed behavior against the updated docs.
4. Record any recovery or rollback notes in the same repo-owned runbook.

Current Runtime Boundaries

Portainer

Portainer owns:

• demo stack definitions
• container image references
• environment variable and mount bindings at stack level

Portainer does not own:

• public hostnames
• Caddy route logic
• application behavior contracts

Caddy

Caddy owns:

• public hostnames
• reverse proxy path routing
• auth host and demo host ingress behavior

Caddy does not own:

• app container composition
• secret values
• application workflow semantics

Vault

Vault owns:

• secret storage
• seal and unseal lifecycle
• bootstrap and recovery material

Vault does not own:

• auth UX behavior
• route ownership
• application feature flags outside secret-backed configuration

Validation Checklist

Before closing any runtime or auth-alignment task:

• Confirm the active plan and mini plan still match the intended work.
• Confirm Portainer stacks match the documented demo service layout.
• Confirm Caddy host and path routing match the documented auth and demo routing contract.
• Confirm Vault paths and operations notes still match the expected runtime secret behavior.
• Confirm no cross-repo ProjectReference violations were introduced while adjusting repo docs or validation scripts.

Rollback Principle

Rollback is not automatic.

If runtime validation fails:

1. stop at the system that drifted
2. restore the last known-good runtime configuration in that system
3. update the repo runbook if the rollback exposed undocumented behavior

Do not treat repo docs and deployed systems as independent sources of truth. They must converge after every runtime-facing change.