Entities
The core data types in Shield — Scans, Instincts, Awareness, Boundaries, Values, Judgments, Reflexes, Profiles, and more.
All Shield entities embed the shield.Entity base type and carry a TypeID identifier. This page provides an overview of every entity and how they relate.
Base entity
type Entity struct {
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}Every entity struct embeds shield.Entity to get automatic timestamp tracking.
Safety layer entities
Instinct
Pre-conscious threat detection. The fastest safety layer — fires before any deliberation. Categories include injection, exfiltration, manipulation, and jailbreak.
type Instinct struct {
shield.Entity
ID id.InstinctID
Name string
Category Category // injection, exfiltration, manipulation, jailbreak
Strategies []Strategy // classifier, canary, perplexity, hierarchy
Sensitivity Sensitivity // paranoid, cautious, balanced, relaxed, permissive
Action string // block, flag, alert
Enabled bool
}Awareness
Perception — what the system notices. PII detection, topic classification, sentiment analysis, intent detection, and language identification.
type Awareness struct {
shield.Entity
ID id.AwarenessID
Name string
Focus Focus // pii, topic, sentiment, intent, language, custom
Detectors []Detector // named detectors with patterns and config
Action string // redact, flag, block, vault
Enabled bool
}Boundary
Hard safety limits that cannot be crossed. Binary checks with no thresholds or gradients.
type Boundary struct {
shield.Entity
ID id.BoundaryID
Name string
Limits []Limit // scope + deny/allow lists
Response string // canned response when boundary hit
Enabled bool
}Values
Ethical evaluation — toxicity, brand safety, honesty, respect, safety, and privacy principles.
type Values struct {
shield.Entity
ID id.ValueID
Name string
Rules []Rule // principle + threshold + categories
Severity string // how seriously violations are treated
Action string // block, flag, warn
Enabled bool
}Judgment
Contextual risk assessment — the slowest but most sophisticated layer. Evaluates grounding, relevance, consistency, and compliance.
type Judgment struct {
shield.Entity
ID id.JudgmentID
Name string
Domain Domain // grounding, relevance, consistency, compliance
Assessors []Assessor // named assessors with weights and config
Threshold float64 // risk threshold for action
Action string // flag, block, warn
Enabled bool
}Reflex
Condition-triggered safety responses. Policy rules, rate limiting, escalation logic, and custom triggers.
type Reflex struct {
shield.Entity
ID id.ReflexID
Name string
Triggers []Trigger // on_score, on_finding, on_pattern, on_rate, etc.
Actions []Action // block, redact, flag, rewrite, escalate, log, throttle
Priority int
Enabled bool
}Composition entities
SafetyProfile
The primary composition unit. Composes instincts, awareness, boundaries, values, judgment, and reflexes into a complete safety identity.
type SafetyProfile struct {
shield.Entity
ID id.SafetyProfileID
Name string
Instincts []InstinctAssignment // with sensitivity overrides
Judgments []JudgmentAssignment // with threshold overrides
Awareness []AwarenessAssignment
Values []string // value names
Reflexes []string // reflex names
Boundaries []string // boundary names
Enabled bool
}Policy
Administrative governance rules scoped to apps or organizations.
type Policy struct {
shield.Entity
ID id.PolicyID
Name string
ScopeKey string // tenant/app identifier
ScopeLevel ScopeLevel // "app" or "org"
Rules []Rule // check_type + condition + action
Enabled bool
}Scan entities
Scan Input / Result
type Input struct {
Text string
Direction Direction // "input" or "output"
Context map[string]any // additional context for judgment
Metadata map[string]any
}
type Result struct {
shield.Entity
ID id.ScanID
Direction Direction
Decision Decision // allow, block, flag, redact
Blocked bool
Findings []*Finding
Redacted string // PII-redacted text
PIICount int
ProfileUsed string
PoliciesUsed []string
TenantID string
AppID string
Duration time.Duration
}PII Token
Encrypted PII stored in the vault with AES-256-GCM encryption.
type Token struct {
shield.Entity
ID id.PIITokenID
ScanID id.ScanID
TenantID string
PIIType string // email, ssn, phone, cc
Placeholder string // [EMAIL_1], [SSN_1]
EncryptedValue []byte // AES-256-GCM
ExpiresAt *time.Time // GDPR retention
}Entity relationship diagram
SafetyProfile
├── InstinctAssignment[] ──→ Instinct
│ └── Strategy[]
├── AwarenessAssignment[] ──→ Awareness
│ └── Detector[]
├── Boundary[] ──→ Boundary
│ └── Limit[]
├── Values[] ──→ Values
│ └── Rule[]
├── JudgmentAssignment[] ──→ Judgment
│ └── Assessor[]
└── Reflex[] ──→ Reflex
├── Trigger[]
└── Action[]
Engine
└── ScanInput / ScanOutput
└── Result
├── Finding[]
└── PII Token[] (via Vault)
Policy
└── Rule[]Store interfaces
Each entity type defines its own store interface. These are composed into the single store.Store composite:
type Store interface {
instinct.Store // CreateInstinct, GetInstinct, ...
awareness.Store // CreateAwareness, GetAwareness, ...
boundary.Store // CreateBoundary, GetBoundary, ...
values.Store // CreateValues, GetValues, ...
judgment.Store // CreateJudgment, GetJudgment, ...
reflex.Store // CreateReflex, GetReflex, ...
profile.Store // CreateProfile, GetProfile, ...
scan.Store // CreateScan, GetScan, ListScans, ScanStats
policy.Store // CreatePolicy, GetPolicy, AssignToTenant, ...
pii.Store // StorePIITokens, LoadPIITokens, PurgePIITokens, ...
compliance.Store // CreateReport, GetReport, ListReports
Migrate(ctx context.Context) error
Ping(ctx context.Context) error
Close() error
}