# SG/Sentinel Developer-Friendliness And The Evidence Graph: What The Engine Knows, And Why That Makes Development Better

**version** v0.27.58
**date** 18 May 2026
**from** Human (project lead)
**to** Architect, Developer (lead), Security, @Dev
**type** Arch brief

---

## What This Is

The ninth brief in the SG/Sentinel series, anchored on a principle that runs under the whole series and now gets named explicitly: **developer-friendliness is not a side effect; it has a direct correlation with the quality of the code.** Making SG/Sentinel effective to develop is a primary design goal, not a nice-to-have, because the easier and more productive the development, the higher the quality of the security code.

The brief then describes a specific feature that embodies this principle, **the evidence graph**: the ability to ask Sentinel "what do you know about me?" and get back a rich, semantic, evidence-based graph of everything the engine currently knows about a given IP address, user, request, or activity, including why decisions were made.

Several ideas travel together:

- **Developer-friendliness as a quality multiplier**, not an afterthought
- **The LLM enables interpretation-based checks** that were previously too hard or expensive
- **The "what do you know about me?" feature, taken to town**: full visibility into Sentinel's current knowledge, as a dev-only capability
- **Dev-only insecure code is safe** because the phase model means it never ships to production
- **The efficiency-mapping principle**: code often gets added to compensate for lack of data access; ask instead where the most efficient place to compute something is
- **The evidence graph as a growing semantic knowledge graph**, built by async agents out-of-band, exposed inbound
- **Vault-per-user**: a vault containing everything known about a user, with anonymity modes from know-nothing to know-everything depending on regulation

## Developer-Friendliness Is A Quality Multiplier

The underlying theme the voice memo named: **everything in SG/Sentinel should be development-friendly, and that is not a side effect.** The voice memo: **"the idea that we're making the development easier and developing more productive, it's not a side effect. Making this development more effective literally has a direct correlation with the quality of the code."**

This is a design principle with teeth. It means that when designing the architecture, **making it developer-friendly is a primary objective, weighted alongside performance and security, not subordinate to them.** The reasoning: security code that is hard to develop, hard to test, hard to understand, and hard to debug is security code that will have bugs, gaps, and weaknesses. Security code that is easy to develop, test, understand, and debug is security code that will be correct. **Developer-friendliness and security quality are the same thing viewed from two angles.**

The voice memo: **"part of our job here, when we design this architecture, is to really make this as developer-friendly as possible, and make this as effective to develop as we can."** Every feature in this brief exists to serve that goal: the evidence graph, the what-do-you-know-about-me capability, the efficiency mapping, all of them make development more effective, which makes the security better.

This connects to the whole series: local-everywhere, the two-way conversation, the dev/main/prod phases, the dangerous dev-only rules, the same-code-everywhere Python advantage. All of these are developer-friendliness features, and the series treats them as central because developer-friendliness is central to security quality.

## The LLM Enables Interpretation-Based Checks

A key enabler the voice memo named: **the LLM in the mix means we can now do checks that require interpretation, which were previously very hard or very complex.**

The voice memo: **"in the past there was a lot of complexity added to rules because we couldn't literally just have what we can now do in an LLM, which is to have a set of checks that require a bit of interpretation. The power of having an LLM in the mix is that we now have an engine that can do interpretation."**

This is why the LLM-first development workflow matters (from the rules-engine brief). Previously, a check that required judgement (is this request pattern suspicious? does this sequence look like an attack? is this an anomaly?) had to be expressed as brittle, complex deterministic rules, or could not be expressed at all. Now, the LLM can do the interpretation, out-of-band, on the analytical timeline.

The consequence for development: **checks that were previously too hard or too expensive to build are now tractable.** The kind of analysis that would have required a research project can now be delegated to an LLM (with the cost element to be figured out). This expands what the security layer can do, and it does so in a development-friendly way: describe the check in natural terms, let the LLM interpret, refine.

Per the earlier briefs, this LLM interpretation runs out-of-band (never inline), on the analytical timeline, feeding results back to the fast deterministic layers. The LLM does the interpretation that informs the rules; the rules do the fast enforcement.

## What Do You Know About Me? Taken To Town

The MVP brief introduced the "what do you know about me?" feature lightly. This brief takes it to town: **a mode where you can ask Sentinel for everything it currently knows about a given IP address, user, request, or activity.**

The voice memo: **"I want to say, what is everything that right now we know about this particular IP address, this request, this user, this activity that we're seeing here, and this is ridiculously valuable, because it really allows us to understand what the server is seeing, and allows us to debug our stuff."**

This is a debugging and development superpower. When something is wrong, when traffic is behaving oddly, when a decision is unexpected, being able to ask Sentinel "what do you know about this?" and get its full current knowledge is invaluable. It exposes:

- What the engine is currently seeing for this IP/user/request
- What evidence it has accumulated
- What decisions it has made and why
- What threat signals it has
- The timing data for the activity

This is a **dev-only capability** by default. The voice memo was clear about the security implications: **"this is probably not something we'll want to have wired up in production, but in development you can see that this is ridiculously valuable."** Exposing everything the engine knows is a security risk in production (it reveals the detection model to an attacker), but in development it is exactly what you need to understand and debug the system.

## Dev-Only Insecure Code Is Safe (Because It Never Ships)

A principle the voice memo crystallised, building on the dangerous-dev-only-rules idea from the interactivity brief: **the best way to ensure code is not exploited in production is to not have the code in production in the first place.**

The voice memo: **"the best way to make sure code is not exploited in production is to not have the code there in the first place. We can create quite insecure and exposed materials that never make it to production."**

This is liberating for development. Because the phase model (dev/main/prod) and the minimal-bundle principle (never ship an uninvoked rule) guarantee that dev-only code does not reach production, **we can build powerful, deliberately-insecure development tooling without endangering production at all.** The what-do-you-know-about-me feature can expose everything in development, because that exposure code is excluded from the production bundle by construction.

The pattern:

| Capability | Dev | Prod |
|------------|-----|------|
| What-do-you-know-about-me (full knowledge dump) | Available | Excluded from bundle |
| Evidence graph (full exposure) | Available | Restricted or excluded |
| Insecure debugging endpoints | Available | Never shipped |
| Full state inspection | Available | Excluded |

The phase model is what makes this safe. The dangerous, insecure, ridiculously-valuable development tools live in dev, are excluded from prod by the bundle build, and so cannot be exploited in production because they are not there. **Development gets maximum power; production gets minimum surface.**

## The Efficiency-Mapping Principle

A subtle but important principle the voice memo named: **a lot of code gets added because you are compensating for not having access to some data. The right question is: where is the most efficient way to do this?**

The voice memo: **"a lot of code sometimes gets added because you're compensating for not having access to some of the data. We should always be able to do this mapping where we ask, where is the most efficient way to do this calculation, where is the most efficient way to calculate this information."**

The insight: code complexity often comes from a layer not having the data it needs, so it reconstructs or recomputes or works around the gap. If the data were available at the right place, the workaround code would not be needed. The efficiency-mapping principle says: **before adding code to compensate for missing data, ask whether the data could be made available at the right place instead.**

The evidence graph is partly an answer to this. If every layer can ask Sentinel "what do you know about this?", then layers do not have to reconstruct knowledge that Sentinel already has. The evidence graph makes Sentinel's knowledge available where it is needed, eliminating the compensating code that would otherwise reconstruct it.

This is the horses-for-courses principle (from the codebase-extension brief) applied to data: compute and store each piece of information at the most efficient place, and make it available rather than forcing other layers to recompute it. **The evidence graph is the mechanism for making Sentinel's knowledge available, so other code does not have to compensate for not having it.**

## The Evidence Graph

The central feature: **a semantic, evidence-based graph of what Sentinel currently knows about an IP address, user, request, or activity, that grows over time.**

The voice memo: **"I would like to know what is the graph, a semantic graph of the current IP address, the current user, and what is the evidence map that we have here that is currently available. This should be an evidence-based graph that grows."**

The graph contains the evidence on which Sentinel bases its decisions:

| Evidence Type | Example |
|---------------|---------|
| Threat reports | A threat report for this user, account, or IP |
| Decision reasons | Why something was blocked (a clear, explicit reason) |
| Activity history | What this IP/user has done over time |
| Behavioural signals | Patterns that inform the benign/malicious decision |
| Fingerprint data | The signals that identify this user (from the timing brief) |
| Sequence state | Where the user is in known action sequences |

The voice memo emphasised the decision-reason point: **"if we block somebody, we should have a very clear reason why that's done, and I want to expose that information."** Every block has an explicit, exposed reason in the evidence graph. The graph is not just data; it is the justification for Sentinel's decisions, made inspectable.

### Built By Async Agents Out-Of-Band, Exposed Inbound

The voice memo named the data-flow: **the evidence is created by the async agents running out-of-band, but we get the data inbound.** The agents (the Layer 3 async/LLM analysis from earlier briefs) build the evidence over time. The evidence graph exposes, inbound, what those agents have produced.

The voice memo: **"some of this data is going to be created by the agents that are running on top of this, the agents running offline out-of-bound, but we can get the data inbound. We're asking what is the data that the Sentinel engine is currently basing its decisions on, and this should be a graph."**

So the flow is: async agents analyse traffic (out-of-band, on the analytical timeline), building evidence about IPs and users; the evidence accumulates in the graph; the what-do-you-know-about-me query exposes the graph inbound. **The slow agents build the knowledge; the graph makes it queryable; the decision draws on it.** This is the "slow analysis, fast enforcement" pattern, with the evidence graph as the shared knowledge between the slow and fast paths.

### The Wire-It-In-First Feedback Loop

A development-philosophy point the voice memo made: **instead of developing the graph in the backend in isolation, first wire in how we get the data and the evidence pack.**

The voice memo: **"instead of going and developing just a graph in the backend, let's first wire it in: how we get that data, how we get that evidence pack."**

This is a feedback-loop discipline. Do not build the evidence graph as an abstract backend feature and then figure out how to populate it. First wire in the data flow (how evidence gets from the async agents to the graph to the query), validate that the loop works end to end, and then enrich the graph. **Wire the loop first, enrich second.** This ensures the graph is grounded in real data flow from the start, not a backend abstraction that may not connect to reality.

## Vault-Per-User

The voice memo proposed a structural idea that connects the evidence graph to the broader platform: **a vault per user, containing everything we know about that user.**

The voice memo: **"we could have a vault per user, and that vault per user contains everything we know about that user, from a threat point of view and from an anonymous activity point of view."**

This is a clean structural home for the evidence graph. Each user (or IP, or fingerprint) gets a vault; the vault holds their evidence graph; the vault grows as the async agents add evidence. This composes with everything in the platform: vaults are the storage primitive, the manager-vault pattern applies, the vault commit history is the evidence audit trail, and the per-user vault is naturally scoped and access-controlled.

### Anonymity Modes: From Know-Nothing To Know-Everything

A crucial nuance the voice memo named: **the anonymity of the platform depends on the user and the regulation, so there should be modes from knowing nothing about the user to knowing everything.**

| Mode | What Sentinel Knows | When |
|------|---------------------|------|
| **Know-nothing** | Minimal; anonymous activity only | Privacy-maximising deployments (e.g. SGN) |
| **Know-some** | Behavioural and threat signals, no identity | Default; security without identity |
| **Know-everything** | Full identity and activity | Regulatory compliance requirements |

The voice memo: **"the anonymity of the platform can depend on the user and the regulation. We could have a mode where we know nothing about the user, which we could do in SGN, and another mode where we know everything for regulatory compliance."**

This makes anonymity a configurable property, not a fixed one. Different deployments, different users, different regulatory contexts get different modes. The evidence graph (and the per-user vault) holds exactly as much as the mode permits.

### Even Knowing The Request, We Do Not Know The Content

A reassuring point the voice memo made about the sensitivity of this data: **even when Sentinel knows the request a user made, it does not know the file contents, because those require decryption keys.**

The voice memo: **"even if we know the request the user made, we should probably be in a situation where we don't know what files it accesses, because you need the decryption keys for that. So even at that level, the data is not that sensitive."**

This is the zero-knowledge property of the platform protecting the evidence graph's sensitivity. Sentinel sees the traffic (requests, patterns, timing) but not the encrypted content (which needs keys Sentinel does not have). So the evidence graph, even in know-everything mode, holds metadata and behaviour, not decrypted content. **The zero-knowledge architecture bounds how sensitive the evidence graph can be: it knows what happened, not what was inside.**

## How This Composes With The Series

| Brief | Relationship |
|-------|--------------|
| MVP brief | The what-do-you-know-about-me feature introduced there, taken to town here |
| Rules-engine brief | The LLM interpretation that enables the harder checks |
| Interactivity brief | The dangerous-dev-only-rules pattern that makes insecure dev tooling safe |
| Time brief | The fingerprint and decision-reason data the evidence graph holds |
| Delegation brief | The efficiency-mapping principle (data at the right place) |
| Codebase-extension brief | Horses-for-courses applied to data placement |
| **This developer-friendliness brief** | **Developer-friendliness as a quality multiplier, realised in the evidence graph** |

The evidence graph is where several threads converge: the async agents (rules engine), the decision (time brief), the fingerprint (time brief), the vault storage (platform), the zero-knowledge property (platform), and the developer-friendliness principle (this brief).

## What This Asks For

Concrete next steps:

1. **Adopt developer-friendliness as a primary design objective**, weighted with performance and security.
2. **Build the what-do-you-know-about-me query** as a dev-only capability, excluded from production bundles.
3. **Build the evidence graph**: a semantic, growing, evidence-based graph per IP/user/request.
4. **Wire the data flow first** (async agents to graph to query) before enriching the graph.
5. **Expose decision reasons** in the graph (every block has a clear, inspectable reason).
6. **Use the LLM for interpretation-based checks** that were previously too hard.
7. **Apply the efficiency-mapping principle** (make data available rather than compensating for its absence).
8. **Build vault-per-user** as the storage home for the evidence graph.
9. **Implement the anonymity modes** (know-nothing to know-everything, per deployment/regulation).
10. **Confirm the zero-knowledge bound** (evidence graph holds metadata, not decrypted content).

Estimated effort: 2-3 weeks for the evidence graph, the what-do-you-know-about-me query, and vault-per-user, building on the async-agent and rules-engine work.

## What This Does Not Try To Be

Deliberate scope limits:

- **Not a production knowledge-exposure feature.** The full what-do-you-know-about-me is dev-only by default.
- **Not user tracking.** The evidence graph is for security decisions and debugging, scoped by anonymity mode.
- **Not decrypted-content analysis.** The zero-knowledge property means content is never in the graph.
- **Not a replacement for the rules engine.** It is the knowledge the rules draw on.
- **Not always know-everything.** Anonymity modes default to minimal; know-everything is for regulatory cases.

## Honest Risks

Three risks:

**Risk 1: The what-do-you-know-about-me feature leaking into production.** Exposing the detection model to attackers would be serious. Mitigation: dev-only by the phase model and bundle build; the same guarantee as the dangerous dev-only rules; audited.

**Risk 2: The evidence graph could become a privacy liability.** Holding rich evidence about users has privacy implications. Mitigation: anonymity modes (default minimal); the zero-knowledge bound (no content); per-user vaults with access control; regulatory-mode only where required.

**Risk 3: The evidence graph could grow unbounded.** Per-user evidence accumulating forever is a storage and privacy problem. Mitigation: retention policies; the graph is evidence for decisions, not a permanent record; prune old evidence; tie retention to the anonymity mode.

## Open Questions

| Question | Notes |
|----------|-------|
| Evidence graph format: semantic graph standard or custom? | Connect to the evidence-pack semantic-graph work from MyFeeds |
| Where does the per-user vault live? | The vault storage substrate; access-controlled |
| Default anonymity mode? | Probably know-some (behavioural, no identity); minimal for SGN |
| Retention policy for evidence? | Tied to anonymity mode; prune old evidence |
| How is the what-do-you-know-about-me query authenticated in dev? | Dev-only; strong auth even in dev |
| Cost of LLM interpretation checks? | To be figured out; the analytical timeline is async so cost is per-analysis |
| How does the graph connect to the fingerprint from the time brief? | The fingerprint is a node; evidence attaches to it |
| Can legit users query their own evidence (the privacy-forward version)? | Yes, scoped; the privacy-respecting what-do-you-know-about-me from the MVP brief |

## Relationship To Previous Briefs

| Date | Document | Relationship |
|---|---|---|
| 18 May | `v0.27.58__arch-brief__sg-sentinel-time-as-first-class-dimension.md` | The fingerprint and decision-reason data the graph holds |
| 18 May | `v0.27.58__arch-brief__sg-sentinel-delegation-and-choke-points.md` | The efficiency-mapping principle |
| 18 May | `v0.27.58__arch-brief__sg-sentinel-as-codebase-extension.md` | Horses-for-courses applied to data placement |
| 18 May | `v0.27.58__arch-brief__sg-sentinel-interactivity-and-deployment-phases.md` | The dangerous-dev-only pattern that makes insecure dev tooling safe |
| 18 May | `v0.27.58__arch-brief__sg-sentinel-rules-engine.md` | The LLM interpretation and async agents that build the evidence |
| 18 May | `v0.27.58__dev-brief__edge-layer-mvp-visibility-blocking-deployment.md` | The what-do-you-know-about-me feature introduced there |
| 17 May | `v0.27.55__strategy-brief__myfeeds-b2b-research-briefings-as-evidence-packs.md` | The semantic-graph and evidence-pack patterns the graph uses |
| 16 May | `v0.27.45__dev-brief__nova-and-agentcore-poc-fastapi.md` | Nova for the interpretation checks |
| 14 May | `v0.27.41__arch-brief__vaults-of-vaults-self-contained-mini-apps.md` | Vault-per-user as a managed vault |

---

## Acceptance Criteria

| # | Criterion | Verification |
|---|-----------|-------------|
| 1 | Developer-friendliness is a stated primary design objective | Reflected in design decisions |
| 2 | The what-do-you-know-about-me query works in dev | Full knowledge exposed in dev |
| 3 | It is excluded from production bundles | Verified; not in prod |
| 4 | The evidence graph holds per-IP/user/request evidence | Graph populated |
| 5 | The data flow is wired first (agents to graph to query) | End-to-end loop works before enrichment |
| 6 | Every block has a clear, inspectable reason in the graph | Decision reasons exposed |
| 7 | LLM interpretation checks work (previously-hard checks) | Interpretation-based rules run |
| 8 | The efficiency-mapping principle is applied | Data made available, not recomputed |
| 9 | Vault-per-user stores the evidence graph | Per-user vaults exist |
| 10 | Anonymity modes work (know-nothing to know-everything) | Mode-appropriate data held |
| 11 | The zero-knowledge bound holds (no decrypted content in the graph) | Content never in the graph |
| 12 | Retention policy prunes old evidence | Graph does not grow unbounded |

---

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).