Specs index¶
Reference
Every normative design spec under .ai/specs/, grouped by layer, with its status and a one-line summary. Specs are the source of truth for how Telha is built; where a spec's prose and the code disagree, the spec's own §14 changelog is the as-built record, and the rest of this documentation follows the code.
How to read Status
A spec's Status line is itself normative: Draft means design settled but not yet peer-reviewed or built; Approved (with or without conditions) means implementation may proceed, or has landed; conditions and follow-ups recorded in Status are tracked to closure in that spec's own §14 changelog. Several specs below carry named review dates and reviewers directly in Status because Telha treats certain algorithm families (temporal correctness, scoring math, security-sensitive credential handling) as requiring recorded sign-off before or alongside implementation.
Core engine (.ai/specs/core-engine/)¶
| Spec | File | Status | Summary |
|---|---|---|---|
| Roaring Bitmap Predicate Acceleration | 2026-07-02-bitmap-predicate-index.md | Draft - design settled; activation/tuning await benchmark evidence | Dense row-id allocation, posting-list maintenance, and the temporal post-validation rule that keeps bitmaps a pure candidate-generation optimization, never a correctness path. |
| Claim Verification - Decomposition, Span Matching & Scoring | 2026-07-02-claim-verification.md | Approved (F7 math review complete) | How a generated draft decomposes into atomic claims, the hybrid matcher that scores each claim against the evidence plan, verdict bands, and the unsupported-claim policy. |
| Code Worker - Tree-sitter AST Projection | 2026-07-02-code-projection.md | Approved | How source code becomes graph structure via tree-sitter: node taxonomy, edge semantics (including best-effort call detection), the v1 language set, and incremental re-ingest. |
| Composite Key Layout & Tenant-Scoped Key Encoding | 2026-07-02-composite-key-layout.md | Draft - for peer review before PR-011 | The exact byte layout of every RocksDB key, the ordering rules, and the KeyCodec/TenantScope/ScanRange API that is the only legal way to construct keys anywhere in the codebase. |
| Confidence Decay & Score Fusion - Mathematical Semantics | 2026-07-02-confidence-decay.md | Approved (F7 math review complete) | The exact mathematics of multi-hop confidence decay, per-edge-type weighting, floor cutoff, and fusion of decay with vector similarity into the final ranking score. |
| Docling Worker - Rich Document Projection | 2026-07-02-docling-projection.md | Draft | How PDF/DOCX/PPTX become graph structure: hierarchical node projection, span emission, table handling, page/bbox metadata, and the failure taxonomy. |
| Email Worker - Envelope Projection & Attachment Fan-out | 2026-07-02-email-projection.md | Approved | .eml/.msg projection: person/message node taxonomy, header-derived edges, thread reconstruction, attachment fan-out, and dedup by Message-ID. |
| Evaluation Harness - Metrics, Datasets & Release Gates | 2026-07-02-eval-harness.md | Approved | The end-to-end evaluation harness: metric definitions (recall@plan, claim-support precision, falsehood rejection, temporal accuracy), dataset governance, and release gates. |
| GDPR Erasure - Physical Deletion in an Append-Only Store | 2026-07-02-gdpr-erasure.md | Approved for build (engineering re-review); legal sign-off outstanding, pre-GA gate | The two erasure classes (tenant-level offboarding, subject-level right-to-be-forgotten) and how physical deletion coexists with the append-only doctrine via a ledgered, staged executor. |
| Generation Orchestration - LlmProvider, Prompt Assembly & Cost Caps | 2026-07-02-generation-orchestration.md | Approved (security review of credential handling complete) | The LlmProvider abstraction, in-binary credential handling, citation-marked prompt assembly, streaming, retries, and per-tenant cost governance for /v1/generate. |
| Covering Temporal Indexes & Global Scan Semantics | 2026-07-02-global-temporal-scan.md | Draft | How the two covering secondary indexes are maintained, the global cross-cutting temporal scan algorithm, horizon-boundary termination, and index/primary consistency doctrine. |
| Partitioned HNSW - Bucket Lifecycle, Persistence & Multi-Bucket Search | 2026-07-02-hnsw-partitioning.md | Draft | The derived-index half of the vector subsystem: time-bucket partitioning, open/sealed lifecycle, persistence layout, and multi-bucket query merge with temporal post-validation. |
| Ingestion Provenance - Sources & Span Ledger | 2026-07-02-ingestion-provenance.md | Draft | Source identity and versioning, content-hash dedup, the token span ledger, and the node-to-span linkage that makes every ingested fact traceable to its exact source bytes. |
| Job Queue - States, Leases & Reaper | 2026-07-02-job-queue-leases.md | Draft | Job states, the lease protocol guaranteeing single-consumer processing, retry/backoff, poison handling, and the reaper that reclaims work from dead workers. |
| Integrated MCP Server - Tools, Sessions & Result Shaping | 2026-07-02-mcp-tools.md | Approved (implemented) | The MCP server built into the core binary: tool schemas and phase availability, session authentication and tenant binding, and result shaping for LLM consumption. |
| Memory Planner - Two-Phase Evidence Selection | 2026-07-02-memory-planner.md | Approved (F7 math review complete) | Phase A (candidate recall) and Phase B (budgeted selection) of evidence planning, the token accounting model, truth/cache separation, and determinism guarantees. |
| Monorepo Topology and Toolchain | 2026-07-02-monorepo-topology.md | Approved | The canonical directory structure, toolchain versions, build conventions, and the three-layer (Rust/TypeScript/Python) architecture every PR must conform to. |
| JSON Query Language - Grammar & Semantics | 2026-07-02-query-language.md | Draft | The complete v1 grammar of the JSON query DSL, its semantics, error taxonomy, cursor rules, and the shared fixture corpus binding core, SDKs, and MCP tools. |
| Schema Inference - Type Lattice & Versioning | 2026-07-02-schema-inference.md | Draft | Zero-schema ingest semantics: the type lattice for merging observed property types per (tenant, label), schema versioning triggers, and time-travel introspection. |
| Snapshot Compare - Temporal Delta Engine | 2026-07-02-snapshot-compare.md | Approved | Delta semantics between two bitemporal coordinates: added/removed/modified nodes and edges, property-level diffs, and streaming pagination. |
| Tabular Worker - Rows-to-Graph Projection | 2026-07-02-tabular-projection.md | Draft | CSV/XLSX projection: rows to nodes, columns to properties with polars-driven type coercion, cross-reference edge detection, and streaming limits for large files. |
| Tombstone Referential Cascade (Append-Only) | 2026-07-02-tombstone-cascade.md | Draft - for peer review before PR-019 | The complete, atomic, strictly append-only write-set for tombstoning a node or edge, and the ghost-edge invariant every historical snapshot must satisfy. |
| Bounded Temporal Traversal Semantics | 2026-07-02-traversal-semantics.md | Draft | Hop semantics, bounds, temporal filtering, cycle handling, determinism, and the budget guard for graph traversal. |
| Vector Storage - Embeddings, Model Registry & Embed Jobs | 2026-07-02-vector-storage.md | Draft | The durable half of the vector subsystem: the vectors CF as source of truth, the embedding-model registry, the EmbeddingProvider trait, and the classified-content exclusion guarantee. |
| Version Record Model & Value Serialization | 2026-07-02-version-record-model.md | Draft | The normative structure of NodeVersion and EdgeVersion, their MessagePack serialization, the value-version byte, and interval/tombstone/provenance semantics. |
| Web Worker - Fetcher Abstraction & Web/SPA Projection | 2026-07-02-web-ingestion.md | Draft | The swappable Fetcher abstraction (Firecrawl vs Playwright), crawl policy, recrawl semantics, and the backend-independent Markdown-to-graph projection. |
| Backup & Restore - Online Point-in-Time Durability | 2026-07-05-backup-restore.md | Approved with conditions; two follow-ups owed before pilot data | Telha's first durability path: online point-in-time backups, a verifiable manifest, an attestable restore procedure, and the erasure-replay seam. |
| Retention Policies & Archival - Lifecycle for an Append-Only Store | 2026-07-05-retention-archival.md | Approved | Per-label/source-kind retention policies, legal holds, the archival slice format, the shared retention/erasure executor, and orphaned-data cleanup. |
| Memory Context Endpoint - Planner Output Without Generation | 2026-07-06-memory-context.md | Approved | Exposes the memory planner as POST /v1/memory/context: the budgeted, scored, permission-scoped evidence set /v1/generate would plan, without calling any LLM. |
| Memory Verify Endpoint - Claim Support Without Generation | 2026-07-06-memory-verify.md | Approved | Exposes the claim-verification engine as POST /v1/memory/verify: a verdict for a caller-supplied claim against current memory, without generating anything. |
| Saved Answers & Staleness - Answers That Know When They Expire | 2026-07-06-saved-answers-staleness.md | Approved | Turns generated answers into durable objects with a dependency model and a staleness state machine, so a saved answer knows when the memory beneath it has moved. |
App layer (.ai/specs/app-layer/)¶
| Spec | File | Status | Summary |
|---|---|---|---|
| Field-Level Encryption - Classification, XChaCha20-Poly1305 & Rotation | 2026-07-02-field-encryption.md | Approved (security review complete) | What gets encrypted (declarative classification), how (XChaCha20-Poly1305, envelope format, key hierarchy), rotation, and the opacity contract that keeps classified fields out of indexing and vector search. |
| Chat Delivery Surface (Teams & Slack) | 2026-07-04-chat-delivery-surface.md | Approved (security review complete) | The app-layer service that is Telha's single chat presence: delivery, callback verification, chat-identity-to-PERSON binding, double-send prevention, and the outbound/inbound protocol split. |
| Human Authentication - OIDC/SSO for Operators & End Users | 2026-07-05-sso-auth.md | Approved | OIDC authorization-code flow with PKCE, server-side sessions, IdP-claim-to-role mapping, and how a login binds to the PERSON identity substrate. |
| Memory Cards - Rendering Watch, Brief & Saved-Answer Notifications in Chat | 2026-07-06-memory-cards.md | Approved (security countersigned) | The Memory Change card, Weekly Memory Brief digest, and Saved Answer Updated card, plus the DM-only/RBAC-checked delivery rule for shared watches. |
Integration (.ai/specs/integration/)¶
| Spec | File | Status | Summary |
|---|---|---|---|
| Data-Split Routing Policy - PostgreSQL vs Telha vs Blob | 2026-07-02-data-split-routing.md | Draft | A normative, reviewable routing test for which data goes to PostgreSQL, which to Telha Core, and which to blob storage, with worked examples and anti-patterns. |
| gRPC Contracts - Services, Tenancy Metadata & Evolution Rules | 2026-07-02-grpc-contracts.md | Draft | The two internal gRPC services (AppLayerService, WorkerService), the signed-token tenancy-propagation protocol, transport selection, and buf-enforced proto evolution rules. |
| Entra/AAD Identity-Alias Connector | 2026-07-04-entra-identity-connector.md | Approved | How Microsoft Entra ID becomes the canonical source of person identity: PERSON/GROUP entities, verified aliases, group membership, and delta sync. |
| Source Connector Framework (SharePoint, Exchange, Slack, Salesforce, ...) | 2026-07-04-source-connector-framework.md | Approved | The common contract every pull-based content connector implements: discovery/sync, mandatory authorship/ownership/ACL/timestamp metadata, and stable external identity. |
| Temporal Clarification Loop ("Telha Asks Back") | 2026-07-04-temporal-clarification.md | Approved (final review, responder-assertion condition incorporated) | How temporal ambiguity becomes a routed, RBAC-gated, one-tap question, and how answers become governed evidence: append-only responses, quorum, and bitemporal correction. |
| Memory Watch - Durable Subscriptions Over the Change Feed | 2026-07-06-memory-watch.md | Approved | Telha's subscription primitive: a durable, tenant-scoped watch over entities, sources, labels, stored queries, clarifications, or saved answers, evaluated asynchronously from the transaction-time index. |
Matching architecture pages¶
Several specs above have a deeper engineering treatment in Architecture; where the architecture page does not yet exist, the spec itself remains the normative reference.
Related¶
- Architecture - the engineering deep-dives drawn from these specs.
- Glossary - definitions for the terms these specs introduce.
- CLI reference - the
telha debug,retention,erase, andbackupcommands that operationalize several of these specs. - Configuration keys - the config sections each spec's
§8(or equivalent) defines.