up

docs/policy/dsl.md

@@ -1,7 +1,7 @@
 # Stella Policy DSL (`stella-dsl@1`)
 
-> **Audience:** Policy authors, reviewers, and tooling engineers building lint/compile flows for the Policy Engine v2 rollout (Sprint 20).
-> **Imposed rule:** Policies that alter reachability or trust weighting must run in shadow mode first with coverage fixtures; promotion to active is blocked until shadow + coverage gates pass.
+> **Audience:** Policy authors, reviewers, and tooling engineers building lint/compile flows for the Policy Engine v2 rollout (Sprint 20).
+> **Imposed rule:** Policies that alter reachability or trust weighting must run in shadow mode first with coverage fixtures; promotion to active is blocked until shadow + coverage gates pass.
 
 This document specifies the `stella-dsl@1` grammar, semantics, and guardrails used by Stella Ops to transform SBOM facts, Concelier advisories, and Excititor VEX statements into effective findings. Use it with the [Policy Engine Overview](overview.md) for architectural context and the upcoming lifecycle/run guides for operational workflows.
 
@@ -9,13 +9,13 @@ This document specifies the `stella-dsl@1` grammar, semantics, and guardrails us
 
 ## 1 · Design Goals
 
-- **Deterministic:** Same policy + same inputs ⇒ identical findings on every machine.
-- **Declarative:** No arbitrary loops, network calls, or clock access.
-- **Explainable:** Every decision records the rule, inputs, and rationale in the explain trace.
-- **Lean authoring:** Common precedence, severity, and suppression patterns are first-class.
-- **Offline-friendly:** Grammar and built-ins avoid cloud dependencies, run the same in sealed deployments.
-- **Reachability-aware:** Policies can consume reachability lattice states (`ReachState`) and evidence scores to drive VEX gates (`not_affected`, `under_investigation`, `affected`).
-- **Signal-first:** Trust, reachability, entropy, and uncertainty signals are first-class so explain traces stay reproducible.
+- **Deterministic:** Same policy + same inputs ⇒ identical findings on every machine.
+- **Declarative:** No arbitrary loops, network calls, or clock access.
+- **Explainable:** Every decision records the rule, inputs, and rationale in the explain trace.
+- **Lean authoring:** Common precedence, severity, and suppression patterns are first-class.
+- **Offline-friendly:** Grammar and built-ins avoid cloud dependencies, run the same in sealed deployments.
+- **Reachability-aware:** Policies can consume reachability lattice states (`ReachState`) and evidence scores to drive VEX gates (`not_affected`, `under_investigation`, `affected`).
+- **Signal-first:** Trust, reachability, entropy, and uncertainty signals are first-class so explain traces stay reproducible.
 
 ---
 
@@ -42,26 +42,26 @@ policy "Default Org Policy" syntax "stella-dsl@1" {
     }
   }
 
-  rule vex_precedence priority 10 {
-    when vex.any(status in ["not_affected","fixed"])
-      and vex.justification in ["component_not_present","vulnerable_code_not_present"]
-    then status := vex.status
-    because "Strong vendor justification prevails";
-  }
-
-  rule reachability_gate priority 20 {
-    when telemetry.reachability.state == "reachable" and telemetry.reachability.score >= 0.6
-    then status := "affected"
-    because "Runtime/graph evidence shows reachable code path";
-  }
-
-  rule trust_penalty priority 30 {
-    when signals.trust_score < 0.4 or signals.entropy_penalty > 0.2
-    then severity := severity_band("critical")
-    because "Low trust score or high entropy";
-  }
-}
-```
+  rule vex_precedence priority 10 {
+    when vex.any(status in ["not_affected","fixed"])
+      and vex.justification in ["component_not_present","vulnerable_code_not_present"]
+    then status := vex.status
+    because "Strong vendor justification prevails";
+  }
+
+  rule reachability_gate priority 20 {
+    when telemetry.reachability.state == "reachable" and telemetry.reachability.score >= 0.6
+    then status := "affected"
+    because "Runtime/graph evidence shows reachable code path";
+  }
+
+  rule trust_penalty priority 30 {
+    when signals.trust_score < 0.4 or signals.entropy_penalty > 0.2
+    then severity := severity_band("critical")
+    because "Low trust score or high entropy";
+  }
+}
+```
 
 High-level layout:
 
@@ -141,10 +141,10 @@ annotate    = "annotate", identifier, ":=", expression, ";" ;
 
 Notes:
 
-- `helper` is reserved for shared calculcations (not yet implemented in `@1`).
-- `else` branch executes only if `when` predicates evaluate truthy **and** no prior rule earlier in priority handled the tuple.
-- Semicolons inside rule bodies are optional when each clause is on its own line; the compiler emits canonical semicolons in IR.
-- `settings.shadow = true` enables shadow-mode evaluation (findings recorded but not enforced). Promotion gates require at least one shadow run with coverage fixtures.
+- `helper` is reserved for shared calculcations (not yet implemented in `@1`).
+- `else` branch executes only if `when` predicates evaluate truthy **and** no prior rule earlier in priority handled the tuple.
+- Semicolons inside rule bodies are optional when each clause is on its own line; the compiler emits canonical semicolons in IR.
+- `settings.shadow = true` enables shadow-mode evaluation (findings recorded but not enforced). Promotion gates require at least one shadow run with coverage fixtures.
 
 ---
 
@@ -152,23 +152,23 @@ Notes:
 
 Within predicates and actions you may reference the following namespaces:
 
-| Namespace | Fields | Description |
-|-----------|--------|-------------|
-| `sbom` | `purl`, `name`, `version`, `licenses`, `layerDigest`, `tags`, `usedByEntrypoint` | Component metadata from Scanner. |
-| `advisory` | `id`, `source`, `aliases`, `severity`, `cvss`, `publishedAt`, `modifiedAt`, `content.raw` | Canonical Concelier advisory view. |
-| `vex` | `status`, `justification`, `statementId`, `timestamp`, `scope` | Current VEX statement when iterating; aggregator helpers available. |
-| `vex.any(...)`, `vex.all(...)`, `vex.count(...)` | Functions operating over all matching statements. |
-| `run` | `policyId`, `policyVersion`, `tenant`, `timestamp` | Metadata for explain annotations. |
-| `env` | Arbitrary key/value pairs injected per run (e.g., `environment`, `runtime`). |
-| `telemetry` | Optional reachability signals. Example fields: `telemetry.reachability.state`, `telemetry.reachability.score`, `telemetry.reachability.policyVersion`. Missing fields evaluate to `unknown`. |
-| `signals` | Normalised signal dictionary: `trust_score` (0–1), `reachability.state` (`reachable|unreachable|unknown|under_investigation`), `reachability.score` (0–1), `reachability.confidence` (0–1), `reachability.evidence_ref` (string), `entropy_penalty` (0–0.3), `uncertainty.level` (`U1`–`U3`), `runtime_hits` (bool). |
-| `secret` | `findings`, `bundle`, helper predicates | Populated when the Secrets Analyzer runs. Exposes masked leak findings and bundle metadata for policy decisions. |
-| `profile.<name>` | Values computed inside profile blocks (maps, scalars). |
-
-> **Reachability evidence gate.** When `reachability.state == "unreachable"` but `reachability.evidence_ref` is missing (or confidence is below the high-confidence threshold), Policy Engine downgrades the state to `under_investigation` to avoid false "not affected" claims.
->
-> **Secrets namespace.** When `StellaOps.Scanner.Analyzers.Secrets` is enabled the Policy Engine receives masked findings (`secret.findings[*]`) plus bundle metadata (`secret.bundle.id`, `secret.bundle.version`). Policies should rely on the helper predicates listed below rather than reading raw arrays to preserve determinism and future compatibility.
-
+| Namespace | Fields | Description |
+|-----------|--------|-------------|
+| `sbom` | `purl`, `name`, `version`, `licenses`, `layerDigest`, `tags`, `usedByEntrypoint` | Component metadata from Scanner. |
+| `advisory` | `id`, `source`, `aliases`, `severity`, `cvss`, `publishedAt`, `modifiedAt`, `content.raw` | Canonical Concelier advisory view. |
+| `vex` | `status`, `justification`, `statementId`, `timestamp`, `scope` | Current VEX statement when iterating; aggregator helpers available. |
+| `vex.any(...)`, `vex.all(...)`, `vex.count(...)` | Functions operating over all matching statements. |
+| `run` | `policyId`, `policyVersion`, `tenant`, `timestamp` | Metadata for explain annotations. |
+| `env` | Arbitrary key/value pairs injected per run (e.g., `environment`, `runtime`). |
+| `telemetry` | Optional reachability signals. Example fields: `telemetry.reachability.state`, `telemetry.reachability.score`, `telemetry.reachability.policyVersion`. Missing fields evaluate to `unknown`. |
+| `signals` | Normalised signal dictionary: `trust_score` (0–1), `reachability.state` (`reachable|unreachable|unknown|under_investigation`), `reachability.score` (0–1), `reachability.confidence` (0–1), `reachability.evidence_ref` (string), `entropy_penalty` (0–0.3), `uncertainty.level` (`U1`–`U3`), `runtime_hits` (bool). |
+| `secret` | `findings`, `bundle`, helper predicates | Populated when the Secrets Analyzer runs. Exposes masked leak findings and bundle metadata for policy decisions. |
+| `profile.<name>` | Values computed inside profile blocks (maps, scalars). |
+
+> **Reachability evidence gate.** When `reachability.state == "unreachable"` but `reachability.evidence_ref` is missing (or confidence is below the high-confidence threshold), Policy Engine downgrades the state to `under_investigation` to avoid false "not affected" claims.
+>
+> **Secrets namespace.** When `StellaOps.Scanner.Analyzers.Secrets` is enabled the Policy Engine receives masked findings (`secret.findings[*]`) plus bundle metadata (`secret.bundle.id`, `secret.bundle.version`). Policies should rely on the helper predicates listed below rather than reading raw arrays to preserve determinism and future compatibility.
+
 Missing fields evaluate to `null`, which is falsey in boolean context and propagates through comparisons unless explicitly checked.
 
 ---
@@ -180,50 +180,50 @@ Missing fields evaluate to `null`, which is falsey in boolean context and propag
 | `normalize_cvss(advisory)` | `Advisory → SeverityScalar` | Parses `advisory.content.raw` for CVSS data; falls back to policy maps. |
 | `cvss(score, vector)` | `double × string → SeverityScalar` | Constructs a severity object manually. |
 | `severity_band(value)` | `string → SeverityBand` | Normalises strings like `"critical"`, `"medium"`. |
-| `risk_score(base, modifiers...)` | Variadic | Multiplies numeric modifiers (severity × trust × reachability). |
-| `reach_state(state)` | `string → ReachState` | Normalises reachability state strings (`reachable`, `unreachable`, `unknown`, `under_investigation`). |
-| `vex.any(predicate)` | `(Statement → bool) → bool` | `true` if any statement satisfies predicate. |
+| `risk_score(base, modifiers...)` | Variadic | Multiplies numeric modifiers (severity × trust × reachability). |
+| `reach_state(state)` | `string → ReachState` | Normalises reachability state strings (`reachable`, `unreachable`, `unknown`, `under_investigation`). |
+| `vex.any(predicate)` | `(Statement → bool) → bool` | `true` if any statement satisfies predicate. |
 | `vex.all(predicate)` | `(Statement → bool) → bool` | `true` if all statements satisfy predicate. |
 | `vex.latest()` | `→ Statement` | Lexicographically newest statement. |
 | `advisory.has_tag(tag)` | `string → bool` | Checks advisory metadata tags. |
 | `advisory.matches(pattern)` | `string → bool` | Glob match against advisory identifiers. |
-| `sbom.has_tag(tag)` | `string → bool` | Uses SBOM inventory tags (usage vs inventory). |
-| `sbom.any_component(predicate)` | `(Component → bool) → bool` | Iterates SBOM components, exposing `component` plus language scopes (e.g., `ruby`). |
+| `sbom.has_tag(tag)` | `string → bool` | Uses SBOM inventory tags (usage vs inventory). |
+| `sbom.any_component(predicate)` | `(Component → bool) → bool` | Iterates SBOM components, exposing `component` plus language scopes (e.g., `ruby`). |
 | `exists(expression)` | `→ bool` | `true` when value is non-null/empty. |
-| `coalesce(a, b, ...)` | `→ value` | First non-null argument. |
-| `days_between(dateA, dateB)` | `→ int` | Absolute day difference (UTC). |
-| `percent_of(part, whole)` | `→ double` | Fractions for scoring adjustments. |
-| `lowercase(text)` | `string → string` | Normalises casing deterministically (InvariantCulture). |
-| `secret.hasFinding(ruleId?, severity?, confidence?)` | `→ bool` | True if any secret leak finding matches optional filters. |
-| `secret.match.count(ruleId?)` | `→ int` | Count of findings, optionally scoped to a rule ID. |
-| `secret.bundle.version(required)` | `string → bool` | Ensures the active secret rule bundle version ≥ required (semantic compare). |
-| `secret.mask.applied` | `→ bool` | Indicates whether masking succeeded for all surfaced payloads. |
-| `secret.path.allowlist(patterns)` | `list<string> → bool` | True when all findings fall within allowed path patterns (useful for waivers). |
-
-All built-ins are pure; if inputs are null the result is null unless otherwise noted.
-
----
-
-### 6.1 · Ruby Component Scope
-
-Inside `sbom.any_component(...)`, Ruby gems surface a `ruby` scope with the following helpers:
-
-| Helper | Signature | Description |
-|--------|-----------|-------------|
-| `ruby.group(name)` | `string → bool` | Matches Bundler group membership (`development`, `test`, etc.). |
-| `ruby.groups()` | `→ set<string>` | Returns all groups for the active component. |
-| `ruby.declared_only()` | `→ bool` | `true` when no vendor cache artefacts were observed for the gem. |
-| `ruby.source(kind?)` | `string? → bool` | Returns the raw source when called without args, or matches provenance kinds (`registry`, `git`, `path`, `vendor-cache`). |
-| `ruby.capability(name)` | `string → bool` | Checks capability flags emitted by the analyzer (`exec`, `net`, `scheduler`, `scheduler.activejob`, etc.). |
-| `ruby.capability_any(names)` | `set<string> → bool` | `true` when any capability in the set is present. |
-
-Scheduler capability sub-types use dot notation (`ruby.capability("scheduler.sidekiq")`) and inherit from the broad `scheduler` capability.
-
----
-
-## 7 · Rule Semantics
-
-1. **Ordering:** Rules execute in ascending `priority`. When priorities tie, lexical order defines precedence.
+| `coalesce(a, b, ...)` | `→ value` | First non-null argument. |
+| `days_between(dateA, dateB)` | `→ int` | Absolute day difference (UTC). |
+| `percent_of(part, whole)` | `→ double` | Fractions for scoring adjustments. |
+| `lowercase(text)` | `string → string` | Normalises casing deterministically (InvariantCulture). |
+| `secret.hasFinding(ruleId?, severity?, confidence?)` | `→ bool` | True if any secret leak finding matches optional filters. |
+| `secret.match.count(ruleId?)` | `→ int` | Count of findings, optionally scoped to a rule ID. |
+| `secret.bundle.version(required)` | `string → bool` | Ensures the active secret rule bundle version ≥ required (semantic compare). |
+| `secret.mask.applied` | `→ bool` | Indicates whether masking succeeded for all surfaced payloads. |
+| `secret.path.allowlist(patterns)` | `list<string> → bool` | True when all findings fall within allowed path patterns (useful for waivers). |
+
+All built-ins are pure; if inputs are null the result is null unless otherwise noted.
+
+---
+
+### 6.1 · Ruby Component Scope
+
+Inside `sbom.any_component(...)`, Ruby gems surface a `ruby` scope with the following helpers:
+
+| Helper | Signature | Description |
+|--------|-----------|-------------|
+| `ruby.group(name)` | `string → bool` | Matches Bundler group membership (`development`, `test`, etc.). |
+| `ruby.groups()` | `→ set<string>` | Returns all groups for the active component. |
+| `ruby.declared_only()` | `→ bool` | `true` when no vendor cache artefacts were observed for the gem. |
+| `ruby.source(kind?)` | `string? → bool` | Returns the raw source when called without args, or matches provenance kinds (`registry`, `git`, `path`, `vendor-cache`). |
+| `ruby.capability(name)` | `string → bool` | Checks capability flags emitted by the analyzer (`exec`, `net`, `scheduler`, `scheduler.activejob`, etc.). |
+| `ruby.capability_any(names)` | `set<string> → bool` | `true` when any capability in the set is present. |
+
+Scheduler capability sub-types use dot notation (`ruby.capability("scheduler.sidekiq")`) and inherit from the broad `scheduler` capability.
+
+---
+
+## 7 · Rule Semantics
+
+1. **Ordering:** Rules execute in ascending `priority`. When priorities tie, lexical order defines precedence.
 2. **Short-circuit:** Once a rule sets `status`, subsequent rules only execute if they use `combine`. Use this sparingly to avoid ambiguity.
 3. **Actions:**
    - `status := <string>` – Allowed values: `affected`, `not_affected`, `fixed`, `suppressed`, `under_investigation`, `escalated`.
@@ -271,30 +271,30 @@ rule vex_strong_claim priority 5 {
 }
 ```
 
-### 9.3 Environment-Specific Escalation
+### 9.3 Environment-Specific Escalation
 
 ```dsl
-rule internet_exposed_guard {
-  when env.exposure == "internet"
-       and severity.normalized >= "High"
-  then escalate to severity_band("Critical")
-  because "Internet-exposed assets require critical posture";
-}
-```
-
-### 9.4 Shadow mode & coverage
-
-- Enable `settings { shadow = true; }` for new policies or major changes. Findings are recorded but not enforced.
-- Provide coverage fixtures under `tests/policy/<policyId>/cases/*.json`; run `stella policy test` locally and in CI. Coverage results must be attached on submission.
-- Promotion to active is blocked until shadow runs + coverage gates pass (see lifecycle §3).
-
-### 9.5 Authoring workflow (quick checklist)
-
-1. Write/update policy with shadow enabled.
-2. Add/refresh coverage fixtures; run `stella policy test`.
-3. `stella policy lint` and `stella policy simulate --fixtures ...` with expected signals (trust_score, reachability, entropy_penalty) noted in comments.
-4. Submit with attachments: lint, simulate diff, coverage results.
-5. After approval, disable shadow and promote; retain fixtures for regression tests.
+rule internet_exposed_guard {
+  when env.exposure == "internet"
+       and severity.normalized >= "High"
+  then escalate to severity_band("Critical")
+  because "Internet-exposed assets require critical posture";
+}
+```
+
+### 9.4 Shadow mode & coverage
+
+- Enable `settings { shadow = true; }` for new policies or major changes. Findings are recorded but not enforced.
+- Provide coverage fixtures under `tests/policy/<policyId>/cases/*.json`; run `stella policy test` locally and in CI. Coverage results must be attached on submission.
+- Promotion to active is blocked until shadow runs + coverage gates pass (see lifecycle §3).
+
+### 9.5 Authoring workflow (quick checklist)
+
+1. Write/update policy with shadow enabled.
+2. Add/refresh coverage fixtures; run `stella policy test`.
+3. `stella policy lint` and `stella policy simulate --fixtures ...` with expected signals (trust_score, reachability, entropy_penalty) noted in comments.
+4. Submit with attachments: lint, simulate diff, coverage results.
+5. After approval, disable shadow and promote; retain fixtures for regression tests.
 
 ### 9.4 Anti-pattern (flagged by linter)
 
@@ -332,7 +332,42 @@ rule catch_all {
 
 ---
 
-## 12 · Versioning & Compatibility
+## 12 · Uncertainty Gates (U1/U2/U3)
+
+Uncertainty gates enforce evidence-quality thresholds before allowing high-confidence VEX decisions. When entropy is too high or evidence is missing, policies should downgrade to \ rather than risk false negatives.
+
+### 12.1 Gate Types
+
+| Gate | Tier Threshold | Blocks | Allows | Remediation |
+|------|---------------|--------|--------|-------------|
+| \ | T1 (\) | \ | \, \ | Upload symbols, resolve unknowns |
+| \ | T2 (\) | \ (warns) | \ with review flag | Populate lockfiles, fix purl resolution |
+| \ | T3 (\) | None (advisory only) | All with caveat | Corroborate advisory, add trusted source |
+
+### 12.2 Uncertainty Gate Rules
+
+### 12.3 Tier-Aware Compound Rules
+
+Combine uncertainty tiers with reachability states for nuanced gating:
+
+### 12.4 Remediation Actions
+
+Policy rules should guide users toward reducing uncertainty:
+
+| Uncertainty State | Remediation Action | Policy Annotation |
+|-------------------|-------------------|-------------------|
+| \ (MissingSymbolResolution) | Upload debug symbols, run \ | \ |
+| \ (MissingPurl) | Generate lockfiles, verify package coordinates | \ |
+| \ (UntrustedAdvisory) | Cross-reference trusted sources, wait for corroboration | \ |
+| \ (Unknown) | Run initial analysis, enable probes | \ |
+
+### 12.5 YAML Configuration for Gate Thresholds
+
+The Policy Engine reads uncertainty gate thresholds from configuration:
+
+---
+
+## 13 · Versioning & Compatibility
 
 - `syntax "stella-dsl@1"` is mandatory.
 - Future revisions (`@2`, …) will be additive; existing packs continue to compile with their declared version.
@@ -340,7 +375,7 @@ rule catch_all {
 
 ---
 
-## 13 · Compliance Checklist
+## 14 · Compliance Checklist
 
 - [ ] **Grammar validated:** Policy compiles with `stella policy lint` and matches `syntax "stella-dsl@1"`.
 - [ ] **Deterministic constructs only:** No use of forbidden namespaces (`DateTime.Now`, `Guid.NewGuid`, external services).
@@ -351,4 +386,4 @@ rule catch_all {
 
 ---
 
-*Last updated: 2025-11-26 (Sprint 0401).* 
+*Last updated: 2025-12-13 (Sprint 0401).*