# Technical Specifications

Formal specifications and design documents for Episteme (StemeDB) features.

---

## Core Specifications

### Governance & Organization

- **[Governance Models](./governance-models.md)** - Authority hierarchies and source classification
  - Source-class tiers (Regulatory, Clinical, Expert, Anecdotal)
  - Decay curves and confidence over time
  - Trust pack distribution and policy federation

- **[Concept Hierarchy](./concept-hierarchy.md)** - Subject/predicate organization
  - Namespace structure
  - Path-based indexing
  - Query optimization via hierarchy

### Query & Retrieval

- **[Visual Hash Query](./visual-hash-query.md)** - Screenshot-based retrieval
  - Perceptual hashing for visual anchoring
  - Drift detection via image comparison
  - Time-travel for "what did I see when I first read this?"

---

## Application Specifications

### Aphoria (Code Linter)

- **[Aphoria Claims API](./aphoria-claims-api.md)** - Claims management design
  - AuthoredClaim vs Observation types
  - Provenance, invariant, consequence structure
  - CLI commands for claim lifecycle

### Domain Modeling

- **[Ontology Layer: Medical Vertical](./ontology-layer-medical-vertical.md)** - Healthcare domain
  - Drug, condition, study, patient ontology
  - Pharma-specific extractors and builders
  - FAERS and PubMed integration patterns

---

## Specification Format

All specifications follow this structure:

```markdown
# Specification Title

## Overview
- Problem being solved
- High-level approach
- Key constraints

## Requirements
- Functional requirements
- Non-functional requirements
- Success criteria

## Design
- Architecture diagrams
- Data structures
- API surface

## Implementation Notes
- Platform-specific details
- Performance considerations
- Testing strategy

## Open Questions
- Unresolved decisions
- Future work
```

---

## Status Legend

| Status | Meaning |
|--------|---------|
| ✅ **Implemented** | Specification fully implemented and tested |
| 🚧 **In Progress** | Partial implementation, actively being built |
| 📝 **Draft** | Specification being written, not yet implemented |
| 💡 **Proposed** | Idea stage, needs more design work |
| 🗄️ **Archived** | Superseded or deprecated |

---

## Current Status

| Specification | Status | Last Updated |
|---------------|--------|--------------|
| Governance Models | ✅ Implemented | Phase 3 |
| Concept Hierarchy | ✅ Implemented | Phase 2 |
| Visual Hash Query | ✅ Implemented | Phase 3A |
| Aphoria Claims API | ✅ Implemented | Aphoria A2 |
| Ontology: Medical | ✅ Implemented | Pilot 2 |

---

## RFCs (Request for Comments)

For proposals and design discussions, see **[RFCs](../rfcs/README.md)**.

RFCs go through a review process before becoming specifications:
1. **RFC Draft** → 2. **Review** → 3. **Accepted** → 4. **Specification** → 5. **Implementation**

---

## Design Principles

All specifications must address:

1. **Epistemic Honesty**: Does it preserve disagreement or force false consensus?
2. **Append-Only**: Can it be implemented without mutating existing data?
3. **Query-Time Resolution**: Is complexity deferred to read time?
4. **Source Attribution**: Does it maintain provenance?
5. **Performance**: What are the latency/throughput characteristics?

---

## Contributing Specifications

### Creating a New Specification

1. **Check for duplicates**: Search existing specs and RFCs
2. **Start with RFC**: Draft as RFC first for feedback
3. **Use template**: Follow the specification format above
4. **Include diagrams**: Add ASCII art or mermaid diagrams
5. **Define success criteria**: How will we know it works?

### Specification Review Process

1. **Author** writes initial draft
2. **Technical review** by domain expert
3. **Architecture review** for system-wide impact
4. **Approval** by project maintainers
5. **Implementation** tracking in roadmap

---

## Related Documents

- **[RFCs](../rfcs/README.md)** - Proposals under review
- **[Architecture](../../architecture.md)** - System overview
- **[Roadmap](../../roadmap.md)** - Implementation timeline
- **[Guides](../guides/README.md)** - How-to guides for developers

---

## See Also

- **[Data Structures](../data-structures.md)** - Core types reference
- **[Consistency Model](../consistency-model.md)** - Conflict resolution
- **[Research](../research/)** - Exploratory design work

---

**[← Back to Documentation Index](../README.md)**