# Policy DSL (stella-dsl@1)

## Module
Policy

## Status
IMPLEMENTED

## Description
Policy loading and evaluation exist but the full `.stella` file DSL format with dedicated parser/compiler/simulator (stella policy lint/compile/simulate) was not found as a standalone tool. Policy evaluation is implemented through structured configuration. However, a full DSL parser/compiler exists in the `StellaOps.PolicyDsl` library.

## What's Implemented
- **DslTokenizer**: `src/Policy/StellaOps.PolicyDsl/DslTokenizer.cs`
  - Full lexer with token types: braces, parens, brackets, comma, semicolon, colon, operators
  - Comment support: single-line (`//`) and multi-line (`/* */`)
  - Source location tracking (line, column) for diagnostics
  - `TokenizerResult` with tokens and diagnostics
- **PolicyParser**: `src/Policy/StellaOps.PolicyDsl/PolicyParser.cs`
  - Parses token stream into `PolicyDocumentNode` AST
  - Metadata, settings, profiles, and rules sections
- **PolicyCompiler**: `src/Policy/StellaOps.PolicyDsl/PolicyCompiler.cs`
  - `Compile(source)` -> `PolicyCompilationResult` with Success, IR Document, SHA256 Checksum, CanonicalRepresentation, Diagnostics
  - Pipeline: Parse -> Build IR -> Serialize canonical -> Compute SHA256 digest
  - Error collection: any `PolicyIssueSeverity.Error` diagnostic fails compilation
- **PolicyIr / PolicyIrSerializer**: `src/Policy/StellaOps.PolicyDsl/PolicyIr.cs`, `PolicyIrSerializer.cs`
  - Intermediate representation: PolicyIrDocument, PolicyIrProfile (maps, envs, scalars), PolicyIrRule
  - Canonical binary serialization for digest computation
- **PolicySyntaxNodes**: `src/Policy/StellaOps.PolicyDsl/PolicySyntaxNodes.cs`
  - AST node types for the DSL grammar
- **DslCompletionProvider**: `src/Policy/StellaOps.PolicyDsl/DslCompletionProvider.cs`
  - IDE-style completion suggestions for the DSL
- **SignalContext**: `src/Policy/StellaOps.PolicyDsl/SignalContext.cs`
  - Runtime signal value provider: HasSignal, GetSignal<T>, SetSignal
  - Extension methods: `SecretSignalContextExtensions.cs`, `AiCodeGuardSignalContextExtensions.cs`
- **PolicyEngineFactory**: `src/Policy/StellaOps.PolicyDsl/PolicyEngineFactory.cs`
  - Factory for creating policy evaluation engines from compiled DSL
- **DiagnosticCodes**: `src/Policy/StellaOps.PolicyDsl/DiagnosticCodes.cs`
  - Structured diagnostic codes for parser/compiler errors
- **SourceLocation**: `src/Policy/StellaOps.PolicyDsl/SourceLocation.cs`
  - Position tracking (offset, line, column) for error reporting
- **Tests**: `src/Policy/__Tests/StellaOps.PolicyDsl.Tests/` (7 test files)
  - PolicyCompilerTests, PolicyEngineTests, SignalContextTests, DslCompletionProviderTests

## What's Missing
- **CLI commands**: No `stella policy lint`, `stella policy compile`, or `stella policy simulate` CLI commands wrapping the DSL library
- **`.stella` file format specification**: No formal grammar specification or documentation of the DSL syntax
- **Policy simulation with DSL**: The `PolicySimulationEngine` in the policy engine does not integrate with DSL-compiled policies
- **DSL-to-PolicyPack bridge**: No converter from compiled DSL IR to the PolicyPackDocument format used by the interop framework
- **Language server protocol (LSP)**: DslCompletionProvider exists but no LSP server for editor integration

## Implementation Plan
- Add CLI commands (`stella policy lint/compile/simulate`) that wrap the PolicyDsl library
- Create DSL grammar specification document
- Build bridge from compiled PolicyIrDocument to PolicyPackDocument for interop
- Integrate DSL compilation into the policy bundle build pipeline

## Related Documentation
- PolicyDsl library: `src/Policy/StellaOps.PolicyDsl/` (16 source files)
- PolicyDsl tests: `src/Policy/__Tests/StellaOps.PolicyDsl.Tests/`
- Policy interop: `src/Policy/__Libraries/StellaOps.Policy.Interop/`