git.stella-ops.org/docs/modules/policy/prep/2025-11-20-policy-engine-29-002-prep.md

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

{
  "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.