Skip to content

Commit 2bb6715

Browse files
mdhellermdheller
committed
Add telemetry signal-control implementation roadmap
1 parent a631d0a commit 2bb6715

1 file changed

Lines changed: 212 additions & 0 deletions

File tree

‎docs/implementation-roadmap.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# SourceOS Telemetry Signal-Control Implementation Roadmap
2+
3+
Status: v0.1 execution baseline
4+
5+
This roadmap turns the telemetry-noise-control specification into implementation work across `sourceos-syncd` and adjacent estate surfaces.
6+
7+
## Completion definition
8+
9+
This work is complete when SourceOS can ingest noisy low-level process, policy, trust, package, and sync evidence and render one privacy-preserving, causally accurate operator event with drill-down evidence.
10+
11+
A complete baseline must demonstrate:
12+
13+
- canonical event envelope support
14+
- process provenance capture
15+
- policy decision normalization
16+
- expected-denial classification
17+
- duplicate suppression and noise budgets
18+
- local-first trust/provenance attestation
19+
- operator narrative generation
20+
- privacy-tiered rendering
21+
- DeliveryExcellence metrics for signal quality
22+
- SocioSphere-ready dashboard contract
23+
24+
## Phase 0 — Specification capture
25+
26+
Status: in progress
27+
28+
Deliverables:
29+
30+
- `docs/telemetry-noise-control-spec.md`
31+
- `docs/canonical-event-envelope.md`
32+
- `docs/implementation-roadmap.md`
33+
- issue backlog
34+
- README integration
35+
36+
Acceptance criteria:
37+
38+
- the doctrine is explicit
39+
- controlled vocabularies exist
40+
- one process-launch example exists
41+
- expected sandbox denials are classified below error severity
42+
43+
## Phase 1 — Event schema package
44+
45+
Target: sourceos-syncd
46+
47+
Deliverables:
48+
49+
- JSON Schema for `sourceos.event.v0.1`
50+
- Rust/Go/TypeScript-compatible schema naming rules, depending on implementation language selected
51+
- controlled-vocabulary validation
52+
- sample events for process, policy, trust, and coalesced telemetry
53+
- schema test fixtures
54+
55+
Acceptance criteria:
56+
57+
- invalid severity/outcome/lane/event-class values fail validation
58+
- required causality fields are enforced
59+
- privacy tier is required
60+
- network trust posture is explicit
61+
62+
## Phase 2 — Process provenance collector
63+
64+
Target: sourceos-syncd / AgentPlane
65+
66+
Deliverables:
67+
68+
- process identity tuple
69+
- parent/root trace assignment
70+
- executable identity record
71+
- package-origin detection hook
72+
- exit status capture
73+
- launch-reason field
74+
75+
Minimum identity tuple:
76+
77+
- pid
78+
- ppid
79+
- uid/gid class
80+
- executable path class
81+
- content hash
82+
- package origin
83+
- signer state
84+
- parent command class
85+
- environment class
86+
87+
Acceptance criteria:
88+
89+
- a shell launch produces one `process.exec` event
90+
- process exit attaches to the same trace
91+
- package-managed binaries are distinguished from user-local and unknown binaries
92+
93+
## Phase 3 — Policy decision normalizer
94+
95+
Target: sourceos-syncd / PolicyFabric
96+
97+
Deliverables:
98+
99+
- policy decision event contract
100+
- semantic outcome mapping
101+
- explanation-code registry
102+
- default expected-denial rules
103+
- file, IPC, network, identity, sync operation classes
104+
105+
Required explanation-code examples:
106+
107+
- `POLICY_EXPECTED_METADATA_BOUNDARY`
108+
- `POLICY_EXPECTED_NETWORK_DISABLED`
109+
- `POLICY_UNEXPECTED_FILE_READ`
110+
- `POLICY_ATTACK_LIKE_PRIVILEGE_BOUNDARY_PROBE`
111+
- `POLICY_DEGRADED_TRUST_LOCAL_ONLY`
112+
113+
Acceptance criteria:
114+
115+
- expected sandbox denies render as `notice` + `blocked_expected`
116+
- unexpected denials render as `warning` unless attack-like
117+
- policy result and semantic outcome are both preserved
118+
119+
## Phase 4 — Trust and package provenance
120+
121+
Target: sourceos-syncd / package tooling / SourceOS base
122+
123+
Deliverables:
124+
125+
- local-first trust evaluation event
126+
- package receipt lookup abstraction
127+
- content hash capture
128+
- signature state capture
129+
- network lookup state field
130+
- degraded verification handling
131+
132+
Acceptance criteria:
133+
134+
- unsigned scripts are not automatically treated as malicious
135+
- package-managed binaries can be locally verified
136+
- trust checks never silently use network access
137+
- degraded trust is explainable
138+
139+
## Phase 5 — Noise budget and coalescing engine
140+
141+
Target: sourceos-syncd / DeliveryExcellence
142+
143+
Deliverables:
144+
145+
- event fingerprint algorithm
146+
- duplicate suppression window
147+
- per-daemon noise budget
148+
- raw-to-canonical event ratio metric
149+
- suppressed event sample references
150+
- severity escalation if repeated events change risk class
151+
152+
Acceptance criteria:
153+
154+
- repeated identical denials collapse into one event
155+
- coalesced event preserves count and evidence samples
156+
- severity is not inflated by duplication alone
157+
- high-volume noisy components can be measured and fixed
158+
159+
## Phase 6 — Operator narrative generator
160+
161+
Target: sourceos-syncd / SocioSphere
162+
163+
Deliverables:
164+
165+
- narrative template registry
166+
- risk readout
167+
- next-action recommendation
168+
- privacy-tier-aware rendering
169+
- forensic drill-down references
170+
171+
Acceptance criteria:
172+
173+
- a noisy shell launch renders as a concise narrative
174+
- private paths are not required for default comprehension
175+
- admin forensic view can reveal exact path/hash/provenance when authorized
176+
177+
## Phase 7 — Dashboard and estate integration
178+
179+
Targets:
180+
181+
- SocioSphere for dashboarding
182+
- PolicyFabric for policy explanation
183+
- AgentPlane for agent/process lineage
184+
- DeliveryExcellence for metrics
185+
186+
Deliverables:
187+
188+
- dashboard card contract
189+
- policy explanation API contract
190+
- agent lineage integration contract
191+
- signal-quality metrics export
192+
193+
Acceptance criteria:
194+
195+
- operator sees one card per causal event
196+
- drill-down exposes evidence without raw-log dumping by default
197+
- metrics show event reduction and false-error suppression
198+
199+
## Turn estimate
200+
201+
From the current state, a solid working baseline should take about 8 focused turns.
202+
203+
Turn 1: capture spec, schema seed, roadmap, backlog, README.
204+
Turn 2: add JSON Schema and sample event fixtures.
205+
Turn 3: add minimal process provenance collector contract/stub.
206+
Turn 4: add policy-decision normalizer and explanation-code registry.
207+
Turn 5: add trust/package provenance contract and local-first posture model.
208+
Turn 6: add coalescing/noise-budget engine design and tests.
209+
Turn 7: add operator narrative contract and sample renderer.
210+
Turn 8: wire README, issues, and cross-repo integration notes for SocioSphere, PolicyFabric, AgentPlane, and DeliveryExcellence.
211+
212+
A production-grade daemon will take additional engineering beyond this baseline, but 8 turns should get us to a coherent, reviewable, implementation-ready foundation.

0 commit comments

Comments
 (0)