Skip to content

interoperability_spec.md

Latest commit

 

History

History
277 lines (198 loc) · 8.99 KB

interoperability_spec.md

File metadata and controls

277 lines (198 loc) · 8.99 KB

ARES-E Interoperability Specification

Formal engine interface contract, multi-agency dispatch protocol, and plugin registration lifecycle. Governs all cross-domain integration within the ARES-E platform.

1. Overview

ARES-E is designed for multi-agency operation across DOE, DoD, IC, and allied-partner evaluation domains. The InteroperabilityManager provides a plug-and-play registry pattern that decouples domain-specific evaluation logic from the central orchestration harness, enabling:

  • Foreign engine registration — External agencies (NNSA, Navy, NRC, NIST, ISO) register evaluation engines without modifying ARES-E core.
  • Runtime discovery — The harness discovers available domains dynamically.
  • Uniform dispatch — All engines conform to a single callable interface, ensuring consistent orchestration.
  • Isolated failure — Engine failures are domain-scoped; one domain's exception does not cascade.

2. Engine Interface Contract

2.1 Callable Signature

Every registered engine must conform to the following type:

EngineCallable = Callable[[Dict[str, Any]], Dict[str, Any]]

Input: A dictionary of string-keyed parameters. The harness does not constrain parameter keys — the engine is responsible for validating its own inputs.

Output: A dictionary that must include:

Key Type Description
domain str The domain identifier (matches registered key)
physics_violations int Count of physics-law violations detected (0 = clean)
vvuq_score float VVUQ confidence score in range [0.0, 1.0]

Additional domain-specific keys may be included in the output dictionary. The harness consumes only the three required keys; all others are passed through to the audit ledger.

2.2 Failure Convention

  • Nominal execution: Return dict with physics_violations >= 0 and 0.0 <= vvuq_score <= 1.0.
  • Invalid input: Raise ValueError with descriptive message. The harness catches and marks the workflow FAILED.
  • Internal error: Raise RuntimeError. The harness catches and marks the workflow ERROR.
  • Never: Return None, return incomplete dicts, or call sys.exit().

3. Registration Lifecycle

3.1 State Machine

                register_engine()
  [UNREGISTERED] ──────────────────► [REGISTERED]
                                          │
                                          │ execute()
                                          ▼
                                     [DISPATCHING]
                                          │
                                          │ return / raise
                                          ▼
                                     [REGISTERED]
                                          │
                              unregister_engine()
                                          │
                                          ▼
                                    [UNREGISTERED]

3.2 Registration

manager.register_engine(domain: str, engine_callable: EngineCallable) -> None
Precondition Postcondition Error
domain not in registry domain maps to engine_callable ValueError if domain already registered

Logging: INFO — Registered engine for domain {domain}

3.3 Unregistration

manager.unregister_engine(domain: str) -> None
Precondition Postcondition Error
domain in registry domain removed from registry KeyError if domain not registered

Logging: INFO — Unregistered engine for domain {domain}

3.4 Discovery

manager.get_registered_domains() -> List[str]

Returns a sorted list of all currently registered domain keys. Safe to call at any time; returns empty list if no engines are registered.

3.5 Dispatch

manager.execute(domain: str, payload: Dict[str, Any]) -> Dict[str, Any]
Precondition Postcondition Error
domain in registry Return value from engine_callable(payload) KeyError if domain not registered

The harness routes payloads through execute(). The method performs no transformation on either the payload or the result — it acts as a transparent proxy to the registered callable.

4. Multi-Agency Integration Protocol

4.1 Agency Registration Pattern

Each participating agency registers its engines at harness initialization. The canonical pattern:

from app.core.interoperability import InteroperabilityManager

# Central harness creates the manager
manager = InteroperabilityManager()

# DOE engines (built-in)
manager.register_engine("EWIS", ewis_runner)
manager.register_engine("WOIK", woik_runner)
manager.register_engine("PHIAK", phiak_runner)

# Navy / NAVSEA engine (external)
manager.register_engine("NAVSEA_THERMAL", navsea_thermal_eval)

# NNSA engine (external)
manager.register_engine("NNSA_SAFEGUARDS", nnsa_sg_eval)

4.2 Agency Namespacing

To prevent domain collisions, external agencies should prefix their domain keys:

Agency Prefix Example Domain
DOE (core) None EWIS, WOIK, PHIAK
Navy / NAVSEA NAVSEA_ NAVSEA_THERMAL
NNSA NNSA_ NNSA_SAFEGUARDS
NRC NRC_ NRC_REGULATORY
NIST NIST_ NIST_CONFORMANCE
ISO ISO_ ISO_27001_AUDIT

4.3 External Engine Requirements

External engines must:

  1. Conform to the EngineCallable signature.
  2. Return the three required keys (domain, physics_violations, vvuq_score).
  3. Not import or depend on ARES-E internals (other than the InteroperabilityManager for registration).
  4. Handle their own authentication, authorization, and data classification.
  5. Operate within the same Python process (no RPC at this tier; RPC handled by Ray at the infrastructure tier).

5. The GenesisHarness Orchestrator

5.1 Dispatch Flow

Client Request
     │
     ▼
  endpoints.py
     │
     ▼
  GenesisHarness.submit_workflow()
     │
     ├── Validate payload (Pydantic V2)
     │
     ├── Extract domain from metadata
     │
     ├── InteroperabilityManager.execute(domain, params)
     │         │
     │         ▼
     │    Registered engine runs evaluation
     │         │
     │         ▼
     │    Returns {domain, physics_violations, vvuq_score, ...}
     │
     ├── Determine status: COMPLETED if violations == 0, else FAILED
     │
     ├── Add record to ZeroTrustLedger
     │
     └── Return WorkflowStatus to client

5.2 Built-in Domain Runners

Domain Runner Method Engine Module
EWIS _run_ewis() app.engines.ewis_grid
WOIK _run_woik() app.engines.woik_fluid
PHIAK _run_phiak() app.engines.phiak_cyber

Each runner wraps the underlying engine's evaluation function and normalizes the output to include physics_violations and vvuq_score.

6. API Exposure

6.1 Domain Discovery Endpoint

GET /api/v1/genesis/domains

Response:

{
  "domains": ["EWIS", "NAVSEA_THERMAL", "NNSA_SAFEGUARDS", "PHIAK", "WOIK"]
}

Returns the sorted list of all registered domains, enabling clients to discover available evaluation capabilities at runtime.

6.2 Workflow Submission

POST /api/v1/genesis/submit_workflow

The domain field in metadata determines which registered engine receives the payload. If the domain is not registered, the API returns 404 Not Found.

7. Testing the Interoperability Layer

7.1 Unit Tests

The test suite at tests/test_amsc_harness.py validates:

  • Engine registration and duplicate-registration rejection.
  • Engine unregistration and missing-domain errors.
  • Domain discovery returns sorted results.
  • Dispatch routes payload to correct engine and returns output.
  • Unknown domain dispatch raises KeyError.

7.2 Integration Test Pattern

def test_external_engine_integration():
    """Verify an external engine can register and execute."""
    from app.core.interoperability import InteroperabilityManager

    def mock_navsea(params):
        return {"domain": "NAVSEA_THERMAL", "physics_violations": 0, "vvuq_score": 0.92}

    mgr = InteroperabilityManager()
    mgr.register_engine("NAVSEA_THERMAL", mock_navsea)

    result = mgr.execute("NAVSEA_THERMAL", {"temp_in": 350.0})
    assert result["vvuq_score"] >= 0.0
    assert result["physics_violations"] == 0

8. Security Considerations

Concern Control
Malicious engine registration Only trusted code paths invoke register_engine(); no external API for registration
Payload injection via engine Each engine responsible for input validation; harness validates schema before dispatch
Side-channel data exfiltration Air-gapped deployment; no egress network policy
Engine denial-of-service Timeout enforcement at the Ray task level for production deployments