This directory contains Process, Requests, and Comments — the engineering log and design repository for Sharc.
Note: Documents here are snapshots in time. They represent design intent, architectural decisions, and execution plans. Unlike
docs/, which reflects the current state of user-facing documentation,PRC/contains specifications, action plans, and historical context.
| Document | Purpose |
|---|---|
| ArchitectureOverview.md | The deep engineering manual — layer-by-layer system design |
| DecisionLog.md | "Why did we do X?" — History of all architectural decisions |
| PerformanceBaseline.md | Current benchmark numbers, allocation tiers, Sharc vs SQLite |
| BenchmarkWorkflow.md | How to run benchmarks — chunk definitions, filter patterns, protocol |
| DependencyPolicy.md | 7-criteria evaluation for any new dependency (zero-dep policy) |
| RecallIdentityPolicy.md | Tiered identity model — when to use rowid vs fingerprint vs GUID |
| Document | Status | Purpose |
|---|---|---|
| JitSQL.md | Active | JitSQL specification — execution hints, view support, PreparedTraversal |
| EncryptionSpec.md | Active | AES-256-GCM page encryption with Argon2id KDF |
| WALDesign.md | Active | Write-Ahead Log read-only support design |
| SecurityModel.md | Active | Threat model, encryption, parser hardening, memory safety |
| ErrorHandling.md | Active | Exception hierarchy and ThrowHelper patterns |
| GraphSupport.md | Active | Graph engine design — context compression, integer-first addressing |
| CompatibilityMatrix.md | Active | SQLite feature support status matrix |
| LayerAsView.md | Active | Views as reusable cursor configurations (ILayer interface) |
| Joins.md | Active | Join implementation — hash join, nested loop, index seek |
| Views.md | Active | View resolution and sqlite_schema integration |
| Document | Status | Purpose |
|---|---|---|
| HotScanMode.md | Implemented | Branchless Read() dispatch via ScanMode enum + jump table |
| CursorUnionOptimization.md | Implemented | Polymorphic cursor projection — PointLookup 430 ns to 108 ns |
| PointLookup100x.md | Implemented | Cold path from 92x to 199x vs SQLite |
| PreparedInterfaces.md | Implemented | IPreparedReader/IPreparedWriter, ThreadLocal template pattern |
| PlanLocalCache.md | Implemented | Plan cache for query compilation |
| Document | Purpose |
|---|---|
| StrategyDecision.md | Why pure managed C# (no P/Invoke, no native deps) |
| PerformanceStrategy.md | Performance goals, zero-alloc design, ADR references |
| BenchmarkProtocol.md | Run-analyze-optimize loop, allocation tiers T0-T5 |
| BenchmarkSpec.md | Fair Sharc vs SQLite benchmark design — 10 categories |
| TestStrategy.md | Testing philosophy — inference-based, TDD workflow |
| DataStructureTests.md | Test plan for core readonly structs and decoders |
| CommitChecklist.md | Pre-commit verification steps |
| Glossary.md | Domain terminology reference |
| Document | Status | Purpose |
|---|---|---|
| JitConceptStatement.md | Design | JIT compilation concept and architecture |
| PotentialJitInternalUse.md | Design | Internal optimization opportunities for JIT |
| WildUserScenariosForJitUse.md | Design | User-facing JIT scenarios and use cases |
| PlanStoredProcedures.md | Design | Stored procedure execution model |
| PlanCoreStoredProcedures.md | Design | Core engine stored procedure implementations |
| PlanGraphStoredProcedures.md | Design | Graph-specific stored procedures |
| PlanVectorBuildingBlocks.md | Design | Vector/embedding storage building blocks |
| Document | Status | Purpose |
|---|---|---|
| ExecutionPlan.md | M1-M14 complete | High-level roadmap — needs M15+ for query pipeline |
| FilterActionPlan.md | Superseded by FilterStar/BakedFilter | Three-phase filter engine redesign |
| WriteActionPlan.md | Phase 1 complete | Write engine implementation — INSERT/UPDATE/DELETE |
| Document | Date | Purpose |
|---|---|---|
| ExecutionTierReport.md | 2026-02-22 | DIRECT vs CACHED vs JIT tier benchmarks |
| QueryPipelineOverview.md | 2026-02-22 | Query pipeline architecture and performance |
These documents remain in the repo for historical context but are no longer authoritative. Read for background understanding only.
| Document | Why Archived |
|---|---|
| StatusReportPhase2.md | Phase 2 milestone snapshot (1,064 tests) — superseded by current test suite |
| BenchGraphSpec.md | SurrealDB competitive benchmark spec — comparison deprioritized |
| ArenaUpgrade.md | Seven-page Arena redesign spec — not yet started, future work |
Internal design reviews and architectural reflections:
| Document | Purpose |
|---|---|
| review/deepReviewPhase1.md | Phase 1 deep review |
| review/reflectionPhase2.md | Phase 2 reflection |
| review/TrustLayerReview.md | Trust layer architecture review |
| review/SandboxArchitecture.md | Sandbox architecture evaluation |
| review/AgentTaxonomy.md | Agent classification taxonomy |
| review/GameTheory.md | Game-theoretic trust analysis |
| review/Entitlement.md | Entitlement model design |
| review/Perform.md | Performance review notes |
| review/WriteLeft.md | Write engine remaining work |
User-facing documentation lives in docs/. Key internal references from docs/:
- docs/TrustSharcGap.md — 14 identified trust layer gaps with fix status
- docs/DistributedTrustArchitecture.md — Distributed trust architecture
- docs/BTreeFingerPrint.md — Fingerprint-based dedup benchmark results
- docs/MultiAgentAccess.md — Multi-agent DataVersion/IsStale pattern
- docs/UsageFriendlyErrors.md — User-friendly error message catalog