Skip to content

README.md

Latest commit

 

History

History
72 lines (59 loc) · 9.9 KB

README.md

File metadata and controls

72 lines (59 loc) · 9.9 KB
Raw

Документація KeyLoad

Головна ідея — одна база для AI-агентів: документи, типізовані таблиці, графи, блоби, черги, події, пошук і часові ряди співіснують і доступні один одному через канонічні посилання. SQL — знайома спільна мова для їх поєднання. Наприклад, один bounded запит читає повідомлення черги, знаходить пов'язані сутності й записує зв'язки у граф знань; зворотний напрямок створює завдання з графа. DatabaseComposition / ADR-067 визначають перший atomic server stage та відділяють його від повного declarative SQL.

KeyLoad поєднує документи, історію подій, надійну доставку, граф, часові ряди та пошук у спільному transaction/authorization/recovery середовищі. Почніть із карти архітектури; owning contracts нижче пояснюють поведінку конкретних функцій. Продуктова специфікація зберігає повний задум, але поточні обов'язкові правила мають пріоритет над її старими DotNext/standalone-first choices.

Функції продукту

Canonical Feature Що описує контракт
DatabaseComposition Одна база: bounded queue→entity→graph і graph→queue atomic derivation через SQL CALL/SDK/MCP; full declarative SQL та RF3 qualification pending
DocumentStorage JSON CRUD/PATCH/CAS, strict scalar/unique indexes, domain-bound atomic batch та persisted command outcomes
RelationalStorage Типізовані рядки в canonical entity storage, primary/type/null та native unique constraints; JOIN/FK — наступні незавершені етапи
EventStreams Expected-revision append, generation/EventId dedup and ordered safe replay; aggregate snapshots remain planned
Messaging Durable queues, scheduled/leased work, fenced ACK/NACK/renew, inbox, topics/groups/contiguous checkpoints; planned remote/recurring workflows
GraphTraversal Atomic edge/adjacency, visible directed bounded BFS; planned cross-partition/ranked graph operations
TimeSeries UTC/sequence samples, idempotency, inclusive bounded ranges; planned retention/aggregates/rollups/chunks and isolated Timescale/ManagedCode comparison
Search Exact vector та request-time lexical/hybrid search, policy/bounds; planned providers, ANN і global retrieval
QueryExecution Bounded Q1 SQL, shared authorized AST, JSON/C# equivalence, Explain/cursors; planned extended/distributed operators
Authorization Persisted identity/API-key verifiers, tenant/resource/row/field grants, PII omission/use rules, epochs і worker privacy
ChangeFeeds Atomic outbox, protected resumable CDC, scalar snapshot+tail, projection checkpoints/pins/generation fencing
BackupRestore Verified local backup/artifacts, clean-target restore, new identity/paused dispatch; planned full cluster-cut recovery
BlobStorage Chunked user blobs/partial reads and typed SDK source present; Accepted protocol, exact-SHA qualification pending

Cluster, callers і delivery

Canonical Feature Що описує контракт
ClusterReplication Orleans RF3 durable protocol, quorum/read barriers, snapshots, minority denial та protected control capacity
ClusterRouting Distinct request grain, distributed directory and activation movement, membership, atomic identity/physical placement; forced-movement qualification pending
StorageRecovery Node-local stores/journals/locks/apply/read lifetime, codec/checkpoints/corruption і process recovery
InternalSerialization Generated Orleans DTO closure, current internal binary formats and strict fail-closed boundaries; prior-format conversion is outside current scope, exact-source qualification pending
ClientApi Typed .NET/CLI transport і retries/errors; official MCP/simple agent source and Accepted mapping, qualification pending
AdminDashboard Захищена read-only адмінпанель: фізичні розміри файлів, фактичний HTTP throughput, каталог/документи/blob metadata та черги без споживання; GitHub qualification pending
ResourceExecution Bounded work/memory/lifetimes, multi-tenant admission/control reserve та honest metrics/telemetry
BenchmarkComparisons Same-corpus correctness, Docker/Aspire native topologies, free-engine scope та graphs тільки з successful GitHub JSON
CodeQuality Central SDK/style/Roslyn analysis, named-symbol/SOLID limits та retained diagnostics
TestInfrastructure TUnit/MTP, actual process recovery і Docker RF3 .NET/MCP suites, versions/platforms та release gates
ReleaseDelivery Four separate workflows: build/tests, isolated benchmarks, release, and website generation from authenticated completed-run results
RepositoryGovernance MCAF policy preservation, local ownership, REQ/AC/ADR, bounded agent tasks і documentation coverage

Owning Feature-специфікації включають окремий ReleaseDelivery контракт. Кожна містить requirements/acceptance, applicable ADRs, current/target slice map, positive/negative/edge/error flows та test/evidence boundaries. Frontend або інші N/A surfaces мають конкретну причину; required future capability не зникає з контракту через відсутність source.

flowchart LR
    Entry[README and architecture map] --> Feature[Owning Feature with REQ and AC]
    Feature --> ADR[Unique ADR with implementation contract]
    ADR --> Source[Actual source or explicit planned paths]
    Feature --> Tests[Named existing or planned tests]
    Source --> Evidence[Exact delivered GitHub evidence]
    Tests --> Evidence
    Backlog[Canonical task tracker] --> Feature
Loading

Рішення, джерела та стан

  • ADR index описує рішення та їхню ідентичність. Accepted означає рішення/контракт; Implemented вимагає поточної implementation/tests/docs та verification evidence.
  • Canonical task tracker є canonical джерелом implementation status; coverage catalog мапить кожну KL-задачу на Feature та ADR і не підміняє tracker.
  • Durability audit та comparison contract визначають вимоги до перевірок і незакриті qualification gates.
  • Детальні existing designs: Q1, admission, bounded reads, replica snapshots, feeds. Feature/ADR links визначають owning acceptance; ці матеріали не оголошують майбутні протоколи готовими.

У source є data/auth/feed/backup, public BlobStorage та official MCP/agent можливості з Accepted contracts; current-format restore, Orleans/Docker RF3 та SDK/MCP flows потребують delivered-source qualification. Нові SQL/typed-row joins мають окремий реєстр доказів. Історичний CI 36926803549 на 9c570f8c33a7a9667507a8e1c0ca68860de3be45 не кваліфікує пізніші зміни.

Product qualification і всі load/test results беруться лише з GitHub Actions; graphs — тільки з raw successful JSON із SHA/run/profile/topology/guarantees. Документальний/static review не доводить швидкість, power-loss durability, numeric coverage/complexity або production readiness. Метод цієї документаційної роботи: ADR-037.

Проміжні JSON-звіти агентів, development checkpoints і копії результатів окремих CI-запусків видалено. У implementation/ залишено п’ять канонічних JSON: статус, карту документаційної traceability, запис перевірки структури репозиторію та два SQL-інвентарі. Оригінальні результати перевірок належать GitHub Actions та його артефактам; історичні твердження у Feature/ADR не кваліфікують поточний checkout.