ORCHESTRA Contract-Test Flow — Cross-Repo Validation Walkthrough¶

ORCHESTRA is the ecosystem's Integration-Tests Authority — a standalone public repo (ecosystem-integration-tests/) that validates cross-repo contracts across the FCC-L2 constellation. Unlike NEXUS (paper handoff) and PHOENIX (open-science + patent), ORCHESTRA is a test project in the engineering sense: a pyproject.toml + pytest + markers + contract modules. Its coordination record captures the contract surface, not the test code itself.

This walkthrough covers how a new cross-repo contract is proposed, authored, tested, gated, and recorded. By the end you will know when ORCHESTRA is the authority you are coordinating with and what the record should look like afterwards.

Actors¶

LAR (Lane-Aware Router Steward) — FCC-side owner on the emission side for event-shape contracts (PAOMBus, UXBus).
OTO (OpenTelemetry Observer) — FCC-side owner on the emission side for observability-shape contracts.
Surface owners — the eight personas that own the FCC plugin entry-point groups (fcc.plugins.personas, fcc.plugins.engines, …). Each owns the contract for their surface.
Partner-repo maintainers — authors of the partner side of each contract.
Coordination steward — you. You do not author contracts; you verify the record reflects them.

The offline-default design philosophy¶

ORCHESTRA's most important design choice is that all default-tier tests are offline-default with clean skip semantics. No HTTP. No subprocess. No database. No credentials. Tests use AST walking and grep-style substring checks against partner source trees.

Why it matters for a steward: if a proposed amendment to the ORCHESTRA record (or a proposed new contract module) introduces mandatory HTTP or credentials into the default tier, push back. Live-mode is available (via explicit markers), but it is strictly opt-in.

Markers and modes¶

Marker	Default	Trigger
`cross_repo`	on	default, fast, offline
`requires_fcc_installed`	off	`FCC_ROOT` env set
`requires_paom_live`	off	`PAOM_LIVE=1`
`requires_aome_live`	off	`AOME_LIVE=1` (AOME on :3100)
`requires_distiller_live`	off	`DISTILLER_LIVE=1` (Distiller on :8002)

The five partners (plus one optional)¶

Every contract test validates at least one of the five partner repos:

Codename	Repo path	Role
CTO	`../attic_om_poc/cto/`	core (ontology)
CRUCIBLE	`../aome_ext/`	core (agentic OM)
PRISM	`../constel_ext/`	core (metadata)
AURORA	`../sky-parlour_poc/sky-parlour/backend/`	application (visualization)
NEXUS	`../research_center_ext/`	foundation (statistical)
SENTINEL	`../paom/`	integration (LLM/router) — optional live-mode only

Tests skip cleanly when a partner repo is not checked out locally. Never fail-hard on missing partners.

The eight contract modules¶

At v1.7.1 ORCHESTRA ships eight contract modules: two legacy (pre-RT-14) plus six RT-14 Sprint 1 additions under tests/contracts/.

Legacy (pre-RT-14)¶

Module	Validates
`test_namespace_registry.py`	`namespaces.yaml` cross-consistency
`test_plugin_discovery.py`	FCC entry-point declarations
`test_vocabulary_roundtrip.py`	Vocabulary provider class-map shape
`test_event_replay.py`	`FederationRegisteredEvent` round-trip
`test_mcp_contract.py`	PAOM → CTO / AOME MCP stubs
`test_http_contract.py`	PAOM HTTP endpoints (live marker)

RT-14 Sprint 1¶

Module	Validates
`test_aome_sid_contract.py`	SID three-layer models + domains + URI prefixes + bus + routes
`test_aome_qa_contract.py`	Q&A models + LLMAdapter Protocol + routes + ideation bundle
`test_aome_distiller_bidirectional.py`	AOME bridge / handlers / clients + Distiller routes + bus subjects
`test_paom_fcc_plugins_aome_consumes.py`	PAOM 8 FCC entry-point groups + AOME PAOM proxy modules
`test_otel_event_boundary.py`	back-office `BUS_*` constants kept out of UX-lane prefixes
`test_a2a_skill_card_complete.py`	JV agent-card parity with `SkillRegistrar` (10 skill_ids)

Walkthrough — authoring a new contract¶

You are a coordination steward observing a proposed new contract from the surface owner's PR. Here is what the end-to-end flow looks like:

Step 1 — Surface owner identifies the new contract¶

The FCC-side surface owner (for example, the persona that owns fcc.plugins.vocabulary_providers) ships a change that alters the contract shape. The owner writes a one-paragraph description: what the contract is, which partners consume it, which markers it needs, what its offline-default check looks like.

Step 2 — Surface owner opens a cross-repo PR to ORCHESTRA¶

The PR adds a new module under ecosystem-integration-tests/tests/contracts/. The module:

Uses AST walking or grep-style substring checks by default (no HTTP, no subprocess).
Skips cleanly on missing partner repos.
Declares any live-mode marker explicitly.

Step 3 — ORCHESTRA review¶

ORCHESTRA maintainers review for:

Offline-default discipline.
Marker correctness.
Skip-semantics cleanliness.
Fixture location (live fixtures go under tests/contracts/fixtures/<partner>/).

Step 4 — CI gate tier decision¶

The new test starts in the advisory tier. Once it has passed reliably for at least one FCC release, the ORCHESTRA team may promote it to required on the per-PR check matrix.

Step 5 — Coordination record amendment¶

At this point the steward enters the flow. The surface owner (or LAR/OTO if event-shape) proposes an amendment to the ORCHESTRA record:

Add a row to the relevant contract-module table (Legacy or RT-14 or a new section).
Update the marker/mode table if a new marker was introduced.
Update Coordination cadence > CI gate evolution table if the tier changed.
Update Handoff artifacts > FCC hands to ORCHESTRA if a new artifact is introduced.

Step 6 — Steward signs off¶

The steward verifies:

The record's cross-repo contract claims match the live PR.
The marker vocabulary stays internally consistent.
The offline-default design philosophy is preserved (no accidental credentials in the default tier).
The module count cited elsewhere in the record is updated (the record says "8 total — 2 legacy + 6 RT-14 additions"; if it becomes 9, update).

CI gate evolution¶

The ORCHESTRA gate has moved through three tiers:

FCC release	Gate status
v1.3.10 and earlier	not yet wired
v1.3.11	advisory — runs on FCC PRs, does not block merge
v1.4.0 – v1.4.4	advisory; partners added contract tests
v1.5.0 – v1.5.x	required-candidate — green required to release, soft-gated
v1.7.1+	required in the per-PR check matrix

The steward's job in a tier change: verify the record table reflects the new tier, and scan for any lingering "advisory" language in prose.

The public-repo responsibility¶

ORCHESTRA is the only public ecosystem project at v1.7.1. It is therefore also the external-facing reproducibility artifact — an auditor, prospective JV partner, or reproducibility reviewer can clone it without special access.

This gives the record a special open item: a "how to evaluate FCC from outside" README section is pending. Stewards should know this is an unresolved item and check progress on it each release.

Steward touchpoints summary¶

Partner matrix — 5 + 1 optional. Verify each partner's repo path is current.
Module matrix — 8 total. Update the count and the per-module row on every new contract.
Marker matrix — 5 markers. Ensure every live-mode marker has a default-off posture.
CI gate table — 5 rows (one per release tier). Update on every tier change.
Fixtures — tests/contracts/fixtures/aome/ is a placeholder at v1.7.1 pending AOME v2.6.0 freeze. Track progress.

Worked example — new namespace contract¶

Imagine FCC adds a twelfth namespace to its 11-ecosystem registry.

Namespace added to src/fcc/federation/namespace.py + data.
test_namespace_registry.py already validates cross-consistency — no new module needed, but the test assertion may need a data fixture update on ORCHESTRA's side.
LAR coordinates with the ORCHESTRA maintainer to update the fixture.
FCC release ships; ORCHESTRA's per-PR gate runs; green.
Steward update — the ORCHESTRA record's Handoff artifacts > Namespace registry line cites "(11 ecosystems)". Update to "(12 ecosystems)". Bump last_updated.

Common failure modes¶

New contract module lands in ORCHESTRA without a record update. The module exists in the test repo but the coordination record does not cite it. Steward catches this by comparing the record's module table against tests/contracts/ on every release.
Module promoted from advisory to required without gate-table update. The CI is now enforcing a contract but the record still shows "advisory". Mitigation: steward reads .github/workflows/ecosystem-integration-tests.yml on every release.
Live-mode marker leaks into default. A contributor accidentally promotes a live-mode dependency into the default tier. Mitigation: the offline-default discipline is stated in the record's Authority role paragraph — steward enforces it in PR review.
Partner repo renamed without path update. One of the five partners moves its root path. Steward catches via a scripted path-existence check.

Where next¶

Compare with NEXUS Handoff Flow (paper handoff) and PHOENIX Open-Science Flow (three-track open-science + IP). To revisit the reading framework, see Reading Coordination Records. To author a new record from scratch (unlikely for ORCHESTRA specifically, likely when a fourth authority lands), see Writing New Coordination Records.