# Policy Interop Framework (JSON Export/Import)

## Module
Policy

## Status
IMPLEMENTED

## Description
Policy interoperability framework enabling bidirectional JSON export/import of policy rules. OPA/Rego export was planned but only JSON export confirmed in source. Includes PolicyPack document format for portable policy bundles. Full interop library exists with JSON import/export, Rego code generation, and schema validation.

## What's Implemented
- **JsonPolicyExporter**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Export/JsonPolicyExporter.cs`
  - `ExportToJsonAsync(PolicyPackDocument, PolicyExportRequest)`: canonical JSON export with deterministic output
  - Environment filtering: merges environment-specific config into base config
  - Remediation stripping option
  - Content-addressed digest: `sha256:{hex}` via SHA256 of canonical JSON
  - `ExportToRegoAsync()`: bridges to RegoCodeGenerator
  - `SerializeCanonical()` / `SerializeToString()` static helpers
- **JsonPolicyImporter**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/JsonPolicyImporter.cs`
  - `ImportAsync(Stream, PolicyImportOptions)` / `ImportFromStringAsync()`
  - Format detection via `FormatDetector` (auto-detect JSON vs Rego)
  - API version validation: `policy.stellaops.io/v2` (with v1 compatibility adapter warning)
  - Kind validation: `PolicyPack` or `PolicyOverride`
  - Structural validation: duplicate gate IDs, duplicate rule names
  - Remediation hint validation (code, actions)
  - Diagnostic codes: FORMAT_UNKNOWN, REGO_USE_IMPORTER, JSON_PARSE_ERROR, VERSION_UNKNOWN, KIND_INVALID, GATE_ID_DUPLICATE, RULE_NAME_DUPLICATE
  - `PolicyImportResult` with Success, Document, DetectedFormat, Diagnostics, GateCount, RuleCount
- **RegoCodeGenerator**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Rego/RegoCodeGenerator.cs`
  - Generates OPA Rego deny rules from PolicyPackDocument
  - Gate type mappings: CvssThreshold, SignatureRequired, EvidenceFreshness, SbomPresence, MinimumConfidence, UnknownsBudget, ReachabilityRequirement
  - Rego v1 syntax support (`import rego.v1`)
  - Environment-specific config extraction
  - Remediation hints as structured output rules
  - Content-addressed digest of generated Rego source
  - Warning collection for unmapped gate types
- **RegoPolicyImporter**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/RegoPolicyImporter.cs`
  - Imports Rego source back into PolicyPackDocument
- **FormatDetector**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/FormatDetector.cs`
  - Auto-detects policy format (JSON, Rego)
- **PolicyPack v2 schema**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Schemas/policy-pack-v2.schema.json`
- **Abstractions**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Abstractions/`
  - `IPolicyExporter`, `IPolicyImporter`, `IRegoCodeGenerator` interfaces
- **Contracts**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Contracts/`
  - `PolicyPackDocument`, `PolicyExportRequest`, `PolicyImportOptions`, `RegoGenerationOptions`, `RegoExportResult`, `PolicyDiagnostic`
- **DI registration**: `src/Policy/__Libraries/StellaOps.Policy.Interop/DependencyInjection/PolicyInteropServiceCollectionExtensions.cs`
- **Evaluation**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/`
- **Tests**: `src/Policy/__Libraries/__Tests/StellaOps.Policy.Interop.Tests/`
  - JsonPolicyExporterTests, JsonPolicyImporterTests, RegoPolicyImporterTests, RegoCodeGeneratorTests, FormatDetectorTests, PolicySchemaValidatorTests
  - Golden file: `Fixtures/golden-policy-pack-v2.json`

## What's Missing
- **YAML import/export**: Only JSON and Rego formats are supported; no YAML PolicyPack format
- **Policy diff/merge**: No tool to diff two PolicyPackDocuments and produce a delta or merge two packs
- **CLI integration**: No `stella policy export --format rego` or `stella policy import` CLI commands wrapping the interop library
- **Round-trip validation**: No automated tests proving JSON -> Rego -> JSON round-trip produces identical PolicyPackDocument
- **OPA evaluation bridge**: Rego code is generated but there is no OPA evaluation service that runs the generated Rego against actual inputs

## Implementation Plan
- Add CLI commands wrapping export/import operations
- Build round-trip test suite (JSON -> Rego -> JSON identity check)
- Consider YAML format support using existing ScorePolicyLoader YAML infrastructure
- Add policy diff/merge utility for comparing policy versions

## Related Documentation
- Interop library: `src/Policy/__Libraries/StellaOps.Policy.Interop/` (6 subdirectories)
- Interop tests: `src/Policy/__Libraries/__Tests/StellaOps.Policy.Interop.Tests/`
- Policy registry: `src/Policy/StellaOps.Policy.Registry/`