Add driver-neutral runtime identity breadcrumbs

[cbusillo]

Objective

Add a driver-neutral Launchplane runtime identity breadcrumb so any tenant can report what Launchplane deployment, artifact, source ref, and preview generation it is actually running.

Finish Line

Stable and preview deployments can expose a non-secret runtime identity that Launchplane records, injects, verifies, and shows in product/environment read models across generic-web, Odoo, and VeriReel-style tenants.

Current Status

State: Created after the CM Odoo preview incident showed that provider state, Launchplane records, and runtime behavior were hard to line up quickly.
Next action: Design and implement the smallest shared runtime identity contract in an isolated worktree, then adopt it in one generic-web path and one Odoo path before broad rollout.
Blocked by: None conceptually; tenant-specific health exposure may require follow-up PRs in product/tenant repos.
Last verified: 2026-05-09; Launchplane records already carry artifact/source/deployment evidence, but runtime health only reports coarse status for Odoo ({"status":"pass"}) and does not expose an observed deployment identity.

Scope

• Define a structured runtime identity payload with product, context, instance, environment kind, deployment record id, artifact id, source git ref, image reference, release tuple id, preview id, preview generation id, and deployed timestamp where known.
• Inject the identity through Launchplane-owned deploy/preview workflows using non-secret env keys such as LAUNCHPLANE_RUNTIME_IDENTITY_JSON, LAUNCHPLANE_DEPLOYMENT_RECORD_ID, LAUNCHPLANE_ARTIFACT_ID, and LAUNCHPLANE_SOURCE_GIT_REF.
• Persist expected identity in deployment/inventory/read-model surfaces without duplicating secret or provider-only state.
• Teach health evidence to optionally capture observed runtime identity and classify match, mismatch, missing, or unverifiable.
• Document tenant adoption for generic web, Odoo, and other product drivers.

Acceptance Criteria

• Deployment and environment inventory/read-model output includes expected runtime identity fields for the current lane.
• Launchplane injects runtime identity into Dokploy application and compose deployments through shared workflow helpers where possible.
• At least one generic-web health endpoint and one Odoo-compatible health path can expose the observed identity using the same contract.
• Health verification records observed identity status without failing legacy tenants that do not yet expose it unless the product profile opts in.
• Operator-facing read models make expected vs observed identity visible enough to diagnose stale routes or stale runtime state.
• Tests cover identity generation, env injection, inventory propagation, health match/mismatch/missing behavior, and read-model serialization.
• Docs update records.md, dokploy-service-deployments.md, product-repo-contract.md, and driver docs with the contract and adoption path.

Relationships

• Related to Replace Odoo staged preview with isolated runtimes #495 because isolated previews should expose preview generation/runtime identity once they stop mutating stable targets.
• Related to Odoo provenance tracking in Track Odoo base-image lifecycle and build-tool provenance #513 but intentionally driver-neutral.
• related: Replace Odoo staged preview with isolated runtimes #495 - Replace Odoo staged preview with isolated runtimes #495

Validation

• Targeted unit tests for contracts, deploy env rendering, inventory propagation, and health evidence parsing.
• uv run python -m unittest or targeted test subset during development, followed by full configured gates before merge.
• Live smoke on one stable lane and one disposable preview after adoption.

Decisions

• Use structured identity first; a single breadcrumb string can exist as a compact display value but should not be the only machine-readable field.
• Keep identity non-secret and safe to expose in health responses and headers.
• Make observed identity verification opt-in or soft-warning during migration so existing tenants are not broken immediately.

Open Questions

• Should the standard public surface be health JSON only, X-Launchplane-Deployment header, /.well-known/launchplane-runtime.json, or all three?
• Should product profiles declare runtime_identity_required=true once a tenant adopts the contract?
• Which tenant should be the first non-Odoo adopter for proving the generic path?

[cbusillo]

Update 2026-05-09: opened PR #518 (code/runtime-identity-breadcrumbs) for the first runtime identity slice. It adds the structured RuntimeIdentity contract, persists expected identity on deployment/inventory records, injects non-secret LAUNCHPLANE_* env into Dokploy application and compose deploys, and documents the tenant adoption path. CI, Security, CodeQL, frontend validate, container scan, and tests are green on the PR. Follow-up remains for observed runtime identity verification/health headers and stricter per-product opt-in enforcement.