Commitc834a773Recorded24 Oct 2026Repositoryfolio

Document concurrent HTTP consistency and pending dependency releases

Changed
 README.md           |  7 ++++---
 docs/shared-http.md | 33 ++++++++++++++++++++++++++++-----
 2 files changed, 32 insertions(+), 8 deletions(-)
Diff
README.mdmodified
@@ -275,9 +275,10 @@ result line, so a partial failure is visible rather than swallowed.
275
276
## Development
277
−278
Requires [Sigil](https://codeberg.org/sigil/sigil) v0.22.15 and sigil-json 0.16.1.
−279
Shared HTTP uses published sigil-mcp 0.18.3 and sigil-http 0.18.8;
−280
see [dependency status](docs/shared-http.md#development-status).
+278
Requires [Sigil](https://codeberg.org/sigil/sigil) v0.22.15, sigil-json 0.16.2,
+279
sigil-mcp 0.18.4 and sigil-http 0.18.8. This unreleased branch currently needs
+280
two dependency overrides pending their publication; see
+281
[dependency status](docs/shared-http.md#development-status) before building.
282
283
```bash
284
# Install dependencies
docs/shared-http.mdmodified
@@ -24,6 +24,12 @@ and ignored; the old local note viewer has been removed.
24
25
## Storage and indexing
26
+27
Validated HTTP tool calls run in separate cooperative tasks. A writer waiting
+28
for another process's store lock leaves independent reads free to complete.
+29
CPU-bound calls still share one thread; they are not preempted. Mutating tool
+30
handlers are serialized through their index flush, including inbox reads that
+31
may backfill ids. Other read tools do not enter that writer queue.
+32
33
Note and project mutations use the cross-process SQLite store lock. Index
34
maintenance never takes that lock: each indexed document is replaced in its
35
own transaction. A per-connection channel mutex keeps concurrent index tasks
@@ -32,6 +38,19 @@ repair stale results after concurrent edits. Files are replaced atomically. Read
38
tools retain their direct read path. A failed index refresh after a saved write
39
is logged without turning that successful write into a failed tool call.
40
+41
HTTP index reads use a separate SQLite connection from census and writes, so
+42
they cannot see that connection's uncommitted rows. A read concurrent with a
+43
write may finish first and see the previous committed state. A read sent after
+44
the write reply sees its committed index update under the existing write-through
+45
and census-retry rules. SQLite consistency is per query and Markdown replacement
+46
is atomic per file; tools have no global snapshot across files and index queries.
+47
Stdio retains one connection and the same cross-process writer coordination.
+48
+49
HTTP tool replies are ordinary JSON-RPC JSON documents sent with chunked
+50
framing. Early validation retains its HTTP errors; an unexpected failure after
+51
response headers are sent becomes a JSON-RPC internal error carrying the same
+52
request id. Clients must consume the complete body before decoding it.
+53
54
A metadata census runs every 15 seconds, reading content only for changed files.
55
Signatures include inode, size and nanosecond timestamps. Files that cannot be
56
read or parsed are retried when their fingerprint changes; database failures
@@ -53,8 +72,12 @@ process environment; keep only its variable name in generated configuration.
72
73
## Development status
74
−56
The linear JSON encoder is published as sigil-json 0.16.1. Legacy initialized
−57
HTTP follow-up requests additionally need the sigil-mcp compatibility fix;
−58
that fix is published in sigil-mcp 0.18.3. Non-ASCII header decoding is fixed
−59
in sigil-http 0.18.8. The lock pins these published releases and can be
−60
installed without redirects.
+75
The released 0.3.3 dependency graph uses sigil-json 0.16.1, sigil-mcp 0.18.3
+76
and sigil-http 0.18.8. This unreleased 0.3.4 branch additionally requires
+77
sigil-json 0.16.2 (less encoding CPU) and sigil-mcp 0.18.4 (opt-in deferred
+78
tools). Those two library changes are prepared in isolated branches. The lock
+79
still records the released graph pending leader approval to publish them;
+80
this branch is not yet installable from its public lock. Prototype builds use
+81
explicit overrides for those two libraries and retain the pinned 0.22.15
+82
runtime family. Release qualification must refresh the lock and verify the
+83
published dependency graph before installation.