sirtimbly/cairnquire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: capture protocol and implementation gaps

Browse Source
This commit is contained in:
Tim Bendt
2026-04-29 00:27:04 -04:00
parent 4a72e1e030
commit 1366f8c5fc
5 changed files with 114 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
notes/discrepancies.md Normal file
View File

@@ -0,0 +1,10 @@
# Documentation Discrepancies
## 2026-04-28
1. The plan and ADRs repeatedly describe a single Go binary, while Milestone 1 also requires `apps/web/` as a separate Vite/Preact app. The current implementation treats the web app as build-time static assets served by the Go binary.
2. Milestone 1 asks for `packages/protocol/` with a protobuf schema, but the sync ADR and protocol spec describe JSON messages over WebSocket. The protocol package currently preserves both a `.proto` placeholder and TypeScript-facing JSON model notes.
3. ADR-005 stores content under `data/files/...`, while Milestone 2 examples use `store/...`. The implementation follows ADR-005 and uses `data/files`.
4. ADR-007 says "No build scripts: Makefile only — no npm install," but the chosen frontend stack requires a Node package install step. The Makefile centralizes it, but the dependency policy needs clarification.
5. The foundation milestone specifies `golang-migrate`, but `go-libsql` integration constraints need a clean validation path. A lightweight internal migrator is used now so the project can move forward.

9
notes/problems.md Normal file
View File

@@ -0,0 +1,9 @@
# Implementation Problems Log
## 2026-04-28
- `go-libsql` is the active official Go binding, but it requires CGO and precompiled native libraries. That weakens the "same source -> same binary hash" goal until the exact build environment is locked down.
- The embedded-replica connector in `go-libsql` rejects an empty primary URL. The foundation therefore uses the local `file:` libsql driver path when no primary is configured, and reserves embedded-replica setup for later sync work.
- Docker verification is currently blocked by the local environment because the daemon socket at `/Users/tim/.orbstack/run/docker.sock` was not reachable during `docker build`.
- The docs do not define a config file format. This implementation uses JSON to keep the bootstrap dependency-free.
- The docs require "all Markdown extensions" but do not define a canonical sample corpus. A representative content sample is included and should be expanded as renderer coverage grows.