git.stella-ops.org/docs/features/checked/policy/policy-dsl.md

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, 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/