# Policy Engine · Path-Aware Observability Prep (POLICY-ENGINE-29-004)

- **Date:** 2025-11-20
- **Depends on:** Path/Scope schema (29-002)
- **Working directory:** `src/Policy/StellaOps.Policy.Engine`

## Metrics (Meter prefix `StellaOps.Policy.Engine`)
- `policy.path.eval.total` (counter) — tags: `tenant`, `subject` (purl/cpe simplified), `result` (`allow|deny|error`), `ruleId` (short slug), `pathMatch` (`exact|prefix|glob`).
- `policy.path.eval.duration.ms` (histogram) — tags: `tenant`, `subject`, `ruleId`.
- `policy.path.eval.cache.hit` (counter) — tags: `tenant`, `cache` (`rule|decision`), `hit` (`true|false`).
- `policy.path.eval.scope.mismatch` (counter) — tags: `tenant`, `reason` (`no-scope|depth-limit|confidence-low`).
- `policy.path.eval.coverage` (gauge/exported via observable gauge) — value: % of observations with matching scope; tags: `tenant`, `source`.

## Logs
- Structured log name `Policy.PathEval` with fields: `tenant`, `ruleId`, `subject` (purl/cpe), `filePath`, `pathMatch`, `pattern`, `confidence`, `decision`, `durationMs`, `evidenceHash`, `correlationId`.
- Errors must include `errorCode` (enum: `scope-missing`, `scope-conflict`, `rule-missing`, `runtime-error`).

## Events (optional OTEL spans)
- Span name: `policy.path.evaluate`; attributes mirror log fields plus `ruleVersion`, `treeDigest?`, `dsseEnvelopeHash?` for replay traces.

## Acceptance for prep completion
- Metric/log/span names and required tags are frozen for downstream instrumentation.
- Implementations must use path/scope schema from 29-002 for tag normalization.
- Targets max cardinality: ruleId short slug (<=32 chars), subject truncated to package name (no version) to keep series bounded.