Design¶
remote-store follows Spec-Driven Development (SDD): every feature starts as a specification before any code is written. Architecture decisions are recorded as ADRs.
Documents¶
- Design Document — the overall design and conventions
- Testing Standards — test quality rules and examples
- Documentation Standards — structure, placement, and cross-linking rules
- Authoring Standards — where files belong (placement)
- Content Rules — keeping prose accurate over time
- Process — the SDD methodology
Specifications¶
- 001: Store API Specification
- 002: Registry & Configuration Specification
- 003: Backend Adapter Contract Specification
- 004: Path Model Specification
- 005: Error Model Specification
- 006: Streaming I/O Specification
- 007: Atomic Writes Specification
- 008: S3 Backend Specification
- 009: SFTP Backend Specification
- 010: Native Path Resolution Specification
- 011: S3-PyArrow Hybrid Backend Specification
- 012: Azure Backend Specification
- 013: Memory Backend Specification
- 014: PyArrow FileSystem Adapter Specification
- 015: Store.child() Specification
- 016: ext.batch - Batch Operations Specification
- 017: ext.transfer - Upload, Download, Cross-Store Transfer Specification
- 018: Glob - Pattern Matching Specification
- 019: ext.observe - Observability Hooks Specification
- 020: Credential Hygiene Specification
- 021: Config Loaders Specification
- 022: Streaming Atomic Writes Specification
- 023: ext.cache - Store-Level Caching Middleware Specification
- 024: ext.partition - Hive-Style Partition Path Helpers Specification
- 025: Retry Policy Specification
- 026: Health Check Specification
- 027: iter_children Specification
- 028: read_text Specification
- 029: Async Store and Backend API Specification
- 030: write_text Specification
- 031: ext.dagster - Dagster Integration Specification
- 032: HTTP Backend Specification
- 033: ext.streams — Stream-Level Wrappers
- 034: ext.integrity — Checksum Verification Helpers
- 035: ContentDigest — Structured File Digest Model
- 036: Seekable Read Specification
- 037: Depth-Limited Listing
- 038: Non-Recursive
get_folder_infoOptimization - 039: TLS CA Bundle Specification
- 040: SQL Blob Backend Specification
- 041: SQL Query Backend Specification
- 042: Parquet Dataset Storage Extension (
ext.parquet) - 043: Resolution Plan Specification
- 044: Microsoft Graph Backend Specification
- 045: WriteResult and User Metadata
- 046: Spec 046 — ext.write Extension
- 047: Spec 047 — Documentation Framework Tooling
- 048: Spec 048 — Testing Architecture
Architecture Decision Records¶
- 0001: Architecture - Store, Registry, Backends
- 0002: Configuration Resolution - No Merging
- 0003: fsspec Is an Implementation Detail
- 0004: Empty Path Semantics in Store
- 0005: Bidirectional Path Resolution via
to_key - 0006: Documentation Architecture - Source of Truth and Audiences
- 0007: Three-Tier Documentation Architecture with docs-src/ and Literate Nav
- 0008: Extension Namespace Contract (
ext.*) - 0009: Glob - Three-Tier Design
- 0010: Observe - Proxy Subclass Pattern
- 0011: Retry - Per-Backend Native Configuration
- 0012: Async Store / Backend API — Hybrid Model
- 0013: Drop Optional-Extension Re-exports from
__init__.py - 0014: Middleware Architecture — Path 1 (ProxyStore + Stream Wrappers)
- 0015: Document ProxyStore in the Public API Reference
- 0016: Seekable Read — Three-Tier Design
- 0017: Seekable Read on Store API
- 0018: SQLAlchemy Backend — Two-Class Architecture with Shared Base
- 0019: Multi-Agent Orchestration Architecture
- 0020: Orchestrate Iterative Convergence Model
- 0021: Microsoft Graph SDK Choice —
httpx+msal - 0022: Microsoft Graph Auth Model — Dual Flows Behind a Token-Provider Protocol
- 0023: Async Monitor-URL Polling as a Shared Backend-Local Module
- 0024:
ResourceLockedError Type - 0025: Async-to-Sync Backend Adapter (
AsyncBackendSyncAdapter) - 0026: Strict-Gate Pattern for Optional Capability Kwargs
- 0027: Single Bridge with Enforcement, Not Layered Mechanisms
- 0028: Testing Architecture with Kind and Stage Axes and HTTP Replay Demotion
Requests for Comments¶
- 0001: RFC-0001: Azure Backend via Direct ADLS Gen2 SDK
- 0002: RFC-0002: PyArrow FileSystemHandler Adapter
- 0003: RFC-0003: S3-PyArrow Read Path Optimization
- 0004: RFC-0004: Streaming Atomic Writes
- 0005: Code Deduplication Analysis
- 0006: Naming Inconsistency Analysis
- 0007: Documentation Cross-Link Rules & Compliance Audit
- 0008: RFC-0008: Parquet Dataset Storage Extension
- 0009: RFC-0009: Multi-Agent Orchestration for Complex Tasks
- 0010: RFC-0010: Microsoft Graph Backend (OneDrive, SharePoint, Teams Files)
- 0011: RFC-0011: WriteResult — Native Write Metadata and Opt-In Hashing
- 0012: RFC-0012: Documentation Graph Model
- 0013: RFC-0013:
list_folders(pattern=…)— Name-Based Glob Filter - 0014: RFC-0014: Dagster Compute Log Manager
Audits¶
- 001: Adversarial Review of v0.5.0
- 002: Design & Spec Compliance Review
- 003: Documentation Quality & Spec Compliance
- 004: Documentation Structural Consistency
- 005: Laziness & Memory Efficiency
- 006: Documentation List Completeness
- 007: Test Behavior Assertions
- 008: Package Bugs (User-Facing)
- 009: Backend-Specifics Visibility in Reference
- 010: Audit 010: Extension Private Module Imports
- 011: Audit-011: Handwritten Docs, v0.23.0+ Gaps
- 012: Audit-012: Documentation Structure — Post-ID-174 Layout
- 013: Docstring Style Compliance
- 014:
_BACKEND_AT_ROOT_GRANDFATHEREDallow-list - 015: Spec-to-Test Traceability
Research¶
- Substrate for Data-Driven Improvement of Agent Workflows
- Research Round 2: Async Store API vs Current Feature Surface (ID-013)
- Async Store / Backend API (ID-013)
- Azure PyArrow Optimization
- Backend Contract Completeness
- Backend Setup & Configuration Guides Expansion
- Benchmark Suite v2 — User-Decision Framing
- HTTP cassette/replay layer — mechanism PoC (BK-181)
- BK-181 PR 2 — S3 cassette/replay infeasibility
- paramiko
ssh-rsahost-key compatibility — empirical findings (BK-198) - Bug Prevention Beyond Testing
- Dagster Extension (
ext.dagster, ID-075) - Depth-Limited Listing
- Documentation Content Longevity
- ID-090 — Docs Landing Page
- Example Testing Across Language Ecosystems
- FastAPI Documentation & CI/CD Patterns
- Feature Discoverability for Agents and Humans
- Google-Style Docstring Migration & Zensical Evaluation
- Backend Health Check (
store.ping()/backend.check_health()) - OBS-003 Hand Decomposition (ID-147)
- TLA+ Spec Augmentation (ID-147)
- TLA+ PoC — WriteResult Spec Consistency (ID-147b)
- ID-211 — HEAD pre-check for flat-namespace backends
- Logging, Monitoring & Tracing for remote-store
lxas Tooling for anllms-full.txt/ Repo-Context Bundle- Architecture: Medallion + Dagster Showcase
- OpenRouter.ai Integration for Claude Code Workflow
- Read-Only HTTP Backend
resolve()Specification Proposal- Retry Policy Configuration (ID-010)
s3-boto3backend lane — PoC and disposition- ID-200 — s3fs error-mapping fidelity in
_S3Base - Seekable Read
- SFTPGo — Comparison and Design Insights
- SQLAlchemy Backends & Composite Store
- Store API Refinement
- Configuration Loaders and Store Config Patterns
- Store Middleware Architecture
- Testing Best Practices for Long-Term Package Quality
- v1.0 Communication & Announcement Plan