feat(oncop): introduce ONCOP v1 — typed cross‑operator protocol with …

[iAlexeze]

Summary

This PR introduces ONCOP v1, the Orkestra Native Cross‑Operator Protocol, as the unified, typed mechanism for cross‑binary observation across autoscaling, status fields, and template resolution. ONCOP replaces ad‑hoc HTTP integrations with a declarative, URL‑inferable protocol that operators can implement consistently.

This is a foundational change that standardises how Orkestra operators observe each other.

---

Motivation

Before this PR, cross‑operator reads relied on:

• handwritten URLs
• inconsistent endpoint shapes
• duplicated logic in autoscale, status.fields, and resolver
• no typed distinction between CR detail, CRD info, metrics, or health
• no caching semantics
• no protocol‑level guarantees

This made cross‑binary autoscaling brittle and operator composition harder than necessary.

ONCOP solves this by introducing a typed, deterministic, cache‑aware protocol for cross‑operator reads.

---

Design Overview

ONCOP defines five observation surfaces:

Type	Description
metrics	Operator‑level metrics
health	Operator health state
cr	CR‑specific detail (status/spec/children/metrics)
info	CRD‑level info
events	CR‑scoped events

Each type maps to a deterministic URL under /katalog/<crd>.

URL inference is centralised in:

• BuildONCOPURL — constructs URLs from CrossCRDDeclaration

Cross resolution now follows a strict priority:

1. Informer registry (same binary)
2. ONCOP host-based URL inference
3. Raw endpoint fallback
4. Empty result

This ensures correctness, performance, and backward compatibility.

---

Implementation Details

1. ONCOPType enum

Added first‑class constants:

• metrics
• health
• cr
• info
• events

With helpers:

• MetricsType
• HealthType
• CRType
• InfoType
• EventsType

2. URL inference

BuildONCOPURL(decl) now constructs URLs using:

• decl.Source.Host
• decl.Source.Type
• decl.Crd
• decl.Selector.Namespace
• decl.Selector.Name

This eliminates all handwritten URLs.

3. readCross() integration

readCross() now includes:

• Path 2a: raw endpoint (unchanged)
• Path 2b: ONCOP host inference (new)

Responses are injected into .cross.<as>.

4. Resolver improvements

Added:

• ParseCrossField
• ExtractCrossCRD
• ExtractCrossCategory
• ExtractCrossFieldName
• ExtractCrossNamespace

These unify parsing of cross.<crd>.<category>.<field>.

5. Autoscale integration

Autoscale conditions now resolve:

cross.<crd>.metrics.<metricName>

via ONCOP metrics endpoint with optional caching.

6. Status fields

Status fields can now reference:

• .cross.<as>.status.*
• .cross.<as>.children.*
• .cross.<as>.metrics.*
• .cross.<as>.health.*

All powered by ONCOP.

---

Migration Notes

• Existing source.endpoint continues to work unchanged.
• Operators may optionally implement ONCOP endpoints to become first‑class subjects.
• type: cr should be used for CR‑specific detail (replaces previous overloading of info).
• No breaking changes to existing Katalogs unless they relied on undocumented URL shapes.

---

Testing

• Added unit tests for URL inference across all ONCOP types
• Added resolver tests for cross‑field parsing
• Added integration tests for autoscale conditions using ONCOP metrics
• Verified fallback behavior: registry → ONCOP → raw endpoint
• Verified caching semantics (cacheFor)
• Verified status.fields resolution using ONCOP CR + health + metrics

---

Reviewer Checklist

• URL inference logic matches ONCOP spec
• readCross() preserves existing behavior for informer + raw endpoint
• CRD selectors correctly propagate namespace/name into ONCOP URLs
• Autoscale conditions resolve metrics via ONCOP
• Status fields resolve CR detail and health via ONCOP
• No regressions in existing Katalogs
• Documentation updated (ONCOP spec + examples)