# Policy Engine · Path/Scope Schema Prep (POLICY-ENGINE-29-002)

- **Date:** 2025-11-20
- **Working directory:** `src/Policy/StellaOps.Policy.Engine`
- **Purpose:** Unblock path-aware evaluation chain (tasks 29-003/004 and overlays 30-001..30-003) by freezing the canonical path/scope schema and examples.

## Schema (authoritative fields)
`PathScope` object used across evaluator inputs, telemetry, and snapshots:
- `tenant` (string, required) — tenant isolation key.
- `subject` (object) — affected asset:
  - `purl` (string) or `cpe` (string) — at least one required.
  - `packagePath` (string, optional) — normalized module path within package (e.g., `lib/utils/a.js`).
  - `osImage` (string, optional) — container image ref if OS-level advisory.
- `locator` (object) — where evidence was found:
  - `filePath` (string, required) — repo or image path using POSIX separators.
  - `digest` (string, optional) — SHA-256 of file content; hex, lowercase.
  - `treeDigest` (string, optional) — Merkle root for build tree snapshot.
- `vulnerability` (object) — identifiers present in evidence (facts only): `cve`, `ghsa`, `osv`, `advisoryId`, `source`.
- `provenance` (object) — `ingestedAt` (ISO-8601 UTC), `evidenceHash` (hex), `connectorId` (string), `dsseEnvelopeHash` (optional hex) for replay.
- `scope` (object) — evaluation bounding box:
  - `pathMatch` (enum) `exact|prefix|glob` with `pattern` (string) using POSIX separators.
  - `confidence` (float 0..1) — how confident the analyzer is about the path binding.
  - `depthLimit` (int, optional) — maximum traversal depth for prefix/glob bindings.

## Determinism
- Canonical ordering: subject fields ordered as listed; pathMatch evaluation uses lexical order, then `confidence` desc, then `filePath` asc for tie-breaking.
- Hashing: `evidenceHash` = SHA-256 over normalized JSON of the observation with sorted properties and UTF-8 encoding.

## Sample payload
```json
{
  "tenant": "acme",
  "subject": {"purl": "pkg:npm/lodash@4.17.21", "packagePath": "lib/isEqual.js"},
  "locator": {"filePath": "src/lib/isEqual.js", "digest": "c1ab..."},
  "vulnerability": {"ghsa": "GHSA-35jh-r3h4-6jhm", "source": "ghsa"},
  "provenance": {"ingestedAt": "2025-11-20T00:00:00Z", "evidenceHash": "4f9b...", "connectorId": "excititor-ghsa"},
  "scope": {"pathMatch": "prefix", "pattern": "src/lib/", "confidence": 0.92, "depthLimit": 3}
}
```

## Acceptance for prep completion
- Path/Scope schema above is frozen for sprint 0125; downstream tasks must align or update this doc and sprint risks if changes occur.
- Sample payload provided for fixtures/tests; hashing and ordering rules documented for determinism.