Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.

docs/signals/cas-promotion-24-002.md

@@ -0,0 +1,34 @@
+# SIGNALS-24-002 · CAS promotion checklist (v1)
+
+Purpose: unblock CAS promotion + signed manifest rollout for callgraph storage so SIGNALS-24-002 can move from BLOCKED to implementation.
+
+## Preconditions
+- CAS bucket created for `signals-callgraphs` with write limited to Signals service principals.
+- Surface bundle mock hash recorded; real scanner cache ETA published.
+- Signed manifest tooling available (sigstore or in-house signer) with add-only policy.
+
+## Steps
+1) Freeze manifest schema (fields: `graph_id`, `digest`, `language`, `source`, `created`, `signer`, `signature`).
+2) Generate manifests for existing callgraphs; store under `cas://signals/manifests/{graph_id}.json`.
+3) Sign each manifest; attach DSSE envelope; store under `cas://signals/manifests/{graph_id}.json.dsse`.
+4) Apply bucket policy: read-only for downstream, write for Signals service; deny deletes.
+5) Configure GC policy: retain manifests indefinitely; callgraph blobs keep 30d rolling unless referenced.
+6) Enable alerts for failed retrievals and missing manifest/DSSE pairs.
+7) Record hash list and signer key IDs in release notes.
+
+## Deliverables
+- Policy document + proof of applied IAM
+- Manifest schema JSON
+- Signed manifest samples (see tests)
+- Hash list of all published callgraphs (sha256)
+
+## Evidence locations (repo paths)
+- Policy & schema: `docs/signals/cas-promotion-24-002.md` (this file)
+- Sample manifest + DSSE: `tests/reachability/corpus/manifest.json` (already present) maps to expected structure.
+
+## Owners
+- Signals Guild (implementation)
+- Platform Storage Guild (policy/approvals)
+
+## Status
+- Checklist published 2025-11-19; awaiting Platform Storage approval to proceed.

docs/signals/events-24-005.md

@@ -0,0 +1,47 @@
+# signals.fact.updated event contract (SIGNALS-24-005 prep)
+
+**Purpose**: replace the in-memory logger used during Signals development with a real event bus contract so reachability caches can be invalidated and downstream consumers (Policy Engine, Notifications, Console) can subscribe deterministically.
+
+## Topic / channel
+- Primary topic: `signals.fact.updated.v1`
+- Dead-letter topic: `signals.fact.updated.dlq`
+- Delivery: at-least-once; consumers must de-duplicate using `event_id`.
+
+## Message envelope
+```jsonc
+{
+  "event_id": "uuid-v4",                // stable across retries; used for idempotency
+  "emitted_at": "2025-11-20T00:00:00Z", // UTC, RFC3339
+  "tenant": "acme",                     // required; lower-case
+  "subject_key": "sbom:sha256:…" ,       // subject of facts (asset, sbom, host). Deterministic model key.
+  "fact_kind": "callgraph" | "runtime" | "reachability" | "signal", // enums mapped from Signals domain
+  "fact_version": 1,                     // monotonically increasing per subject_key + fact_kind
+  "digest": "sha256:…",                 // CAS digest of canonical fact document
+  "content_type": "application/json",   // or application/vnd.stellaops.ndjson when chunked
+  "producer": "StellaOps.Signals",      // emitting service
+  "source": {
+    "pipeline": "signals",             // consistent with Observability tags
+    "release": "0.4.0-alpha"           // optional
+  },
+  "trace": {
+    "trace_id": "…",                   // pass-through if available
+    "span_id": "…"
+  }
+}
+```
+
+## Routing / partitions
+- Partition key: `tenant` to keep per-tenant ordering.
+- Retry policy: exponential backoff up to 5 minutes; move to DLQ thereafter with `dlq_reason` header.
+
+## Consumer expectations
+- De-duplicate on `event_id` and `digest`.
+- Fetch fact body from CAS using `digest`; avoid embedding large payloads in the message.
+- If consumer cannot resolve CAS, treat as transient and retry later (do not drop).
+
+## Security / air-gap posture
+- No PII; tenant id only.
+- Works offline when bus is intra-cluster (e.g., NATS/Redis Streams); external exporters disabled in sealed mode.
+
+## Provenance
+- This contract supersedes the temporary log-based publisher referenced in Signals sprint 0143 Execution Log (2025-11-18). Aligns with `signals.fact.updated@v1` payload shape already covered by unit tests.

docs/signals/provenance-24-003.md

@@ -0,0 +1,31 @@
+# SIGNALS-24-003 · Provenance appendix checklist (v1)
+
+Purpose: unblock provenance enrichment for runtime facts so SIGNALS-24-003 can advance once CAS promotion is approved.
+
+## Required fields (per runtime fact)
+- `callgraph_id` (matches CAS manifest id)
+- `ingested_at` (UTC ISO-8601), `received_at`
+- `tenant`
+- `source` (host/service emitting facts)
+- `pipeline_version` (git SHA or build ID)
+- `provenance_hash` (sha256 of raw fact blob)
+- `signer` (key id) and optional `rekor_uuid` or `skip_reason: offline`
+
+## Steps
+1) Freeze provenance JSON schema (`provenance.runtime.fact.v1`).
+2) Add enrichment stage writing provenance into CAS alongside runtime facts.
+3) Emit DSSE attestation per batch of runtime facts; store in CAS.
+4) Update `/signals/runtime-facts/ndjson` handler to return `provenance_hash` and `callgraph_id` when available.
+5) Add validation tests to ensure add-only evolution and deterministic ordering.
+
+## Deliverables
+- Schema file: `docs/signals/provenance-24-003.md` (this file) with field list and invariants.
+- Test fixtures: reuse `tests/reachability/corpus/*/vex.openvex.json` provenance anchors; add `provenance_hash` coverage to `ReachabilityLatticeTests` when available.
+
+## Owners
+- Signals Guild (implementation)
+- Runtime Guild (schema review)
+- Authority Guild (signing/attestation)
+
+## Status
+- Checklist published 2025-11-19; awaiting schema/signing approval to proceed.