From 1366f8c5fc02c60bf34b8dd9d0846ab790ef1cbd Mon Sep 17 00:00:00 2001 From: Tim Bendt Date: Wed, 29 Apr 2026 00:27:04 -0400 Subject: [PATCH] docs: capture protocol and implementation gaps --- notes/discrepancies.md | 10 ++++++ notes/problems.md | 9 +++++ openapi/openapi.yaml | 56 ++++++++++++++++++++++++++++++ packages/protocol/README.md | 11 ++++++ packages/protocol/simplesync.proto | 28 +++++++++++++++ 5 files changed, 114 insertions(+) create mode 100644 notes/discrepancies.md create mode 100644 notes/problems.md create mode 100644 openapi/openapi.yaml create mode 100644 packages/protocol/README.md create mode 100644 packages/protocol/simplesync.proto diff --git a/notes/discrepancies.md b/notes/discrepancies.md new file mode 100644 index 0000000..be36ee7 --- /dev/null +++ b/notes/discrepancies.md @@ -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. + diff --git a/notes/problems.md b/notes/problems.md new file mode 100644 index 0000000..1e98802 --- /dev/null +++ b/notes/problems.md @@ -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. diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 0000000..dd8bd12 --- /dev/null +++ b/openapi/openapi.yaml @@ -0,0 +1,56 @@ +openapi: 3.1.0 +info: + title: MD Hub Secure Foundation API + version: 0.1.0 +servers: + - url: http://localhost:8080 +paths: + /health: + get: + summary: Health check + operationId: getHealth + responses: + "200": + description: Healthy + content: + application/json: + schema: + type: object + properties: + status: + type: string + database: + type: string + contentStore: + type: string + /api/uploads: + post: + summary: Upload a single attachment + operationId: uploadAttachment + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + responses: + "201": + description: Attachment stored + /attachments/{hash}: + get: + summary: Download an attachment by content hash + operationId: getAttachment + parameters: + - in: path + name: hash + required: true + schema: + type: string + responses: + "200": + description: Attachment content + diff --git a/packages/protocol/README.md b/packages/protocol/README.md new file mode 100644 index 0000000..a4fb342 --- /dev/null +++ b/packages/protocol/README.md @@ -0,0 +1,11 @@ +# Protocol Package + +This directory exists because the milestone plan expects a shared protocol package. + +For now: + +- `simplesync.proto` captures an eventual strongly typed schema +- `docs/specs/simplesync-protocol.md` remains the more complete behavioral reference + +The current docs still need a final decision on whether wire messages are JSON, protobuf-over-WebSocket, or JSON generated from protobuf definitions. + diff --git a/packages/protocol/simplesync.proto b/packages/protocol/simplesync.proto new file mode 100644 index 0000000..0c96ce8 --- /dev/null +++ b/packages/protocol/simplesync.proto @@ -0,0 +1,28 @@ +syntax = "proto3"; + +package mdhub.protocol.v1; + +option go_package = "github.com/tim/md-hub-secure/packages/protocol/gen/go/mdhub/protocol/v1;protocolv1"; + +message SyncRequest { + string client_id = 1; + string root_hash = 2; + map files = 3; +} + +message SyncResponse { + string server_root_hash = 1; + repeated string missing_from_client = 2; + repeated string missing_from_server = 3; + repeated string conflicts = 4; +} + +message ContentRequest { + string hash = 1; +} + +message ContentResponse { + string hash = 1; + bytes content = 2; +} +