stemedb/docs/specs/README.md

Technical Specifications

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

---

Core Specifications

Governance & Organization

• Governance Models - 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 - Subject/predicate organization

  • Namespace structure
  • Path-based indexing
  • Query optimization via hierarchy

Query & Retrieval

• Visual Hash Query - 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 - Claims management design
  • AuthoredClaim vs Observation types
  • Provenance, invariant, consequence structure
  • CLI commands for claim lifecycle

Domain Modeling

• Ontology Layer: Medical Vertical - Healthcare domain
  • Drug, condition, study, patient ontology
  • Pharma-specific extractors and builders
  • FAERS and PubMed integration patterns

---

Specification Format

All specifications follow this structure:

# 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 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 - Proposals under review
• Architecture - System overview
• Roadmap - Implementation timeline
• Guides - How-to guides for developers

---

See Also

• Data Structures - Core types reference
• Consistency Model - Conflict resolution
• Research - Exploratory design work

---

← Back to Documentation Index