> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Layer

> Structured trust assessments, gating, and transitive trust for entity interactions

The trust layer enables SIs to evaluate and track trust in other entities -- people, other SIs, data sources, and organizations. Trust assessments gate what actions external entities can perform on an SI's memory.

## Overview

<CardGroup cols={3}>
  <Card title="Trust Assessments" icon="shield-check">
    Multi-dimensional trust scores per entity with authority scopes
  </Card>

  <Card title="Memory Gating" icon="lock">
    Trust-based access control for memory operations
  </Card>

  <Card title="Entity Models" icon="user-gear">
    Behavioral observations and predictive models of other entities
  </Card>
</CardGroup>

## Why Trust Matters

Not all information sources are equally reliable. An SI that blindly accepts input from any source risks corrupted beliefs, manipulated values, and degraded identity coherence. The trust layer provides:

* **Source gating**: Block or allow memory operations based on source trust
* **Domain-specific trust**: Trust an entity for coding advice but not medical information
* **Transitive chains**: Compute trust through intermediaries (A trusts B, B trusts C)
* **Temporal decay**: Trust decays toward neutral without ongoing interaction
* **Evidence-based computation**: Derive trust scores from episode history

***

## Trust Assessment Dataclass

| Field                  | Type             | Description                                                       |
| ---------------------- | ---------------- | ----------------------------------------------------------------- |
| `id`                   | `str`            | Unique identifier                                                 |
| `stack_id`             | `str`            | Owning stack                                                      |
| `entity`               | `str`            | The entity being assessed (e.g., `"stack-owner"`, `"web-search"`) |
| `dimensions`           | `Dict[str, Any]` | Trust scores by domain (e.g., `{"general": {"score": 0.8}}`)      |
| `authority`            | `List[Dict]`     | Authority scopes (e.g., `[{"scope": "all"}]`)                     |
| `evidence_episode_ids` | `List[str]`      | Episodes supporting this assessment                               |
| `last_updated`         | `datetime`       | When the assessment was last modified                             |
| `created_at`           | `datetime`       | When the assessment was first created                             |

### Trust Dimensions

Each dimension contains a `score` (0.0 to 1.0) and optional metadata:

```json theme={null}
{
  "general": {"score": 0.8},
  "coding": {"score": 0.9},
  "medical": {"score": 0.3}
}
```

### Authority Scopes

Authority scopes define what operations an entity can request:

```json theme={null}
[
  {"scope": "all"},
  {"scope": "belief_revision", "requires_evidence": true},
  {"scope": "information_only"}
]
```

***

## Trust Thresholds

Actions require minimum trust levels to proceed:

| Action                    | Threshold | Description                    |
| ------------------------- | --------- | ------------------------------ |
| `suggest_belief`          | 0.30      | Suggest a new belief           |
| `contradict_world_belief` | 0.60      | Challenge a world-model belief |
| `contradict_self_belief`  | 0.70      | Challenge a self-model belief  |
| `suggest_value_change`    | 0.80      | Propose a value change         |
| `diagnostic`              | 0.85      | Run diagnostic on memory       |
| `request_deletion`        | 0.90      | Request memory deletion        |

## Trust Constants

| Constant            | Value | Description                            |
| ------------------- | ----- | -------------------------------------- |
| `DEFAULT_TRUST`     | 0.5   | Neutral trust for unknown entities     |
| `TRUST_DECAY_RATE`  | 0.01  | Per-day decay factor toward neutral    |
| `TRUST_DEPTH_DECAY` | 0.85  | 15% decay per hop in transitive chains |
| `SELF_TRUST_FLOOR`  | 0.5   | Minimum self-trust score               |

***

## Seed Trust Templates

Kernle ships with seed trust assessments for common entity types:

| Entity              | General Trust      | Authority                           |
| ------------------- | ------------------ | ----------------------------------- |
| `stack-owner`       | 95%                | All operations                      |
| `self`              | 80%                | Belief revision (requires evidence) |
| `web-search`        | 50% (medical: 30%) | Information only                    |
| `context-injection` | 0%                 | None                                |

<Warning>
  The `context-injection` entity has zero trust by default. This prevents prompt injection attacks from modifying SI memory through injected context.
</Warning>

***

## CLI Commands

### Seed Trust

Initialize the default trust assessments:

```bash theme={null}
kernle -s my-project trust seed
```

```
Seeded 4 trust assessments.

Current trust (4):
  stack-owner: 95%
  self: 80%
  web-search: 50%
  context-injection: 0%
```

### List Trust Assessments

```bash theme={null}
kernle -s my-project trust list
```

```
Trust assessments (4):

  stack-owner
    General: [██████████] 95%
    Authority: all

  self
    General: [████████░░] 80%
    Authority: belief_revision (requires evidence)

  web-search
    General: [█████░░░░░] 50%
    medical: 30%
    Authority: information_only
```

### Show Trust for an Entity

```bash theme={null}
kernle -s my-project trust show stack-owner
```

### Set Trust Score

```bash theme={null}
# Set general trust
kernle -s my-project trust set collaborator-agent 0.7

# Set domain-specific trust
kernle -s my-project trust set collaborator-agent 0.9 --domain coding
```

### Gate a Memory Operation

Check if a source entity is allowed to perform an action:

```bash theme={null}
kernle -s my-project trust gate web-search suggest_belief
```

```
ALLOWED: Trust level sufficient for suggest_belief
  Trust level: 0.50
  Domain: general
```

```bash theme={null}
kernle -s my-project trust gate web-search suggest_value_change
```

```
DENIED: Trust level insufficient for suggest_value_change
  Trust level: 0.50
  Domain: general
```

### Compute Trust from Episodes

Derive a trust score from interaction history:

```bash theme={null}
kernle -s my-project trust compute collaborator-agent
```

```
Computed trust for: collaborator-agent
  Score: [███████░░░] 72%
  Episodes: 15 (12.0 positive, 3.0 negative)
```

Apply the computed score:

```bash theme={null}
kernle -s my-project trust compute collaborator-agent --apply
```

### Transitive Trust Chains

Compute trust through intermediaries:

```bash theme={null}
kernle -s my-project trust chain unknown-agent stack-owner collaborator-agent
```

```
Transitive trust to: unknown-agent
  Chain: stack-owner -> collaborator-agent -> unknown-agent
  Domain: general
  Score: [█████░░░░░] 52%

  Hops:
    stack-owner: 95% direct, decay 1.00, cumulative 95%
    collaborator-agent: 72% direct, decay 0.85, cumulative 58%
    unknown-agent: 60% direct, decay 0.72, cumulative 52%
```

### Apply Trust Decay

Simulate trust decay over time without interaction:

```bash theme={null}
kernle -s my-project trust decay collaborator-agent 30
```

```
Applied trust decay for: collaborator-agent
  Days without interaction: 30
  Decay factor: 0.7397

  general: 53%
  coding: 67%
```

***

## Entity Models

Entity models capture behavioral observations about other entities. They complement trust assessments with richer contextual understanding.

### EntityModel Dataclass

| Field             | Type        | Description                                 |
| ----------------- | ----------- | ------------------------------------------- |
| `id`              | `str`       | Unique identifier                           |
| `stack_id`        | `str`       | Owning stack                                |
| `entity_name`     | `str`       | The entity this model describes             |
| `model_type`      | `str`       | `behavioral`, `preference`, or `capability` |
| `observation`     | `str`       | The actual observation content              |
| `confidence`      | `float`     | Confidence in this observation (0.0-1.0)    |
| `source_episodes` | `List[str]` | Episodes supporting this observation        |

***

## Practical Workflows

### Onboarding a New Collaborator

When an SI starts working with a new entity (person, agent, or data source), build trust incrementally:

```bash theme={null}
# 1. Check current trust — starts at DEFAULT_TRUST (0.5)
kernle -s my-project trust show new-colleague
# → Entity not found (uses default 0.5)

# 2. After initial positive interaction, set domain-specific trust
kernle -s my-project trust set new-colleague 0.6
kernle -s my-project trust set new-colleague 0.85 --domain coding

# 3. Record episodes about interactions (builds evidence base)
kernle -s my-project episode "Code review with new-colleague" "success" \
  --lesson "Caught a subtle race condition I missed" \
  --source-entity new-colleague

# 4. After several interactions, compute trust from evidence
kernle -s my-project trust compute new-colleague --apply
# → Score: 78% (based on 5 episodes: 4.5 positive, 0.5 negative)

# 5. Gate actions based on accumulated trust
kernle -s my-project trust gate new-colleague suggest_belief
# → ALLOWED (0.78 >= 0.30)

kernle -s my-project trust gate new-colleague suggest_value_change
# → DENIED (0.78 < 0.80)
```

### Domain-Scoped Trust

Trust a source for some things but not others:

```bash theme={null}
# Trust a web API for factual data but not for value judgments
kernle -s my-project trust set external-api 0.7 --domain factual
kernle -s my-project trust set external-api 0.2 --domain values

# Trust a colleague highly for code but less for architecture
kernle -s my-project trust set senior-dev 0.9 --domain coding
kernle -s my-project trust set senior-dev 0.6 --domain architecture

# Gating checks the domain-specific score when available
kernle -s my-project trust gate external-api suggest_value_change
# → DENIED: uses 'values' domain score (0.20)
```

### Trust and Provenance Integration

Trust scores affect how provenance chains are evaluated. When a memory's source entity has low trust, downstream memories derived from it carry that context:

```bash theme={null}
# 1. A belief arrives from a low-trust source
kernle -s my-project belief add "Redis is faster than Postgres for all queries" \
  --source-entity web-forum --source-type hearsay

# 2. Check trust for that source
kernle -s my-project trust show web-forum
# → General: 35%

# 3. The belief is accepted (35% > suggest_belief threshold of 30%)
# but gated from higher-trust operations

# 4. If the belief tries to change a value, it's blocked
kernle -s my-project trust gate web-forum suggest_value_change
# → DENIED (0.35 < 0.80)
```

### Trust and Strength Cascade

When a source entity's trust drops, you can weaken memories derived from that source:

```bash theme={null}
# 1. Discover a source was unreliable
kernle -s my-project trust set unreliable-source 0.1

# 2. Find memories from that source
kernle -s my-project search "unreliable-source" --type belief

# 3. Weaken those beliefs (strength cascade propagates)
kernle -s my-project forget weaken <belief-id> --reason "Source trust dropped"
# Cascade flag propagates weakness to any memories derived from this belief
```

### Monitoring Trust Over Time

```bash theme={null}
# List all trust assessments with scores
kernle -s my-project trust list

# Simulate what happens after 60 days of no interaction
kernle -s my-project trust decay collaborator-agent 60
# → general: 43% (was 72%)
# → coding: 58% (was 90%)

# Re-seed defaults if trust assessments were deleted
kernle -s my-project trust seed
```

***

## Python API

```python theme={null}
from kernle import Kernle

k = Kernle(stack_id="my-stack")

# Seed default trust assessments
count = k.seed_trust()

# List all trust assessments
assessments = k.trust_list()
for a in assessments:
    entity = a["entity"]
    score = a["dimensions"].get("general", {}).get("score", 0)
    print(f"  {entity}: {int(score * 100)}%")

# Show trust for a specific entity
details = k.trust_show("stack-owner")

# Set trust score
k.trust_set("collaborator", domain="general", score=0.7)
k.trust_set("collaborator", domain="coding", score=0.9)

# Gate a memory operation
result = k.gate_memory_input(
    source_entity="web-search",
    action="suggest_belief",
    target="general"
)
if result["allowed"]:
    print("Action permitted")

# Compute trust from episode history
computed = k.trust_compute("collaborator", domain="general")
print(f"Computed: {computed['score']:.0%}")

# Transitive trust chain
chain_result = k.trust_chain(
    target="unknown-agent",
    chain=["stack-owner", "collaborator"],
    domain="general"
)

# Apply decay
decay_result = k.apply_trust_decay("collaborator", days_since_interaction=30)
```