Changelog

All notable changes to folio are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.3.4] - 2026-10-25

Dispatch validated HTTP tool calls in separate cooperative tasks, so a writer waiting on a store lock does not hold up independent reads. Mutating handlers remain serialized through their index flush; existing cross-process file locking is preserved.
Use a separate HTTP index connection for reads, keeping uncommitted census/write rows private. Concurrent reads can finish before an in-flight write and see its previous committed state. Reads still have per-query SQLite consistency and atomic Markdown files, without a global multi-file snapshot. The 15-second outside-edit census is unchanged.
Reduce JSON response encoding CPU with sigil-json's native string escaping. Require sigil-json 0.16.2 and sigil-mcp 0.18.4. HTTP tool replies remain JSON-RPC JSON documents and use chunked responses; stdio is unchanged.
Skip unused snippets in note-list searches while retaining default search-index snippets, ranking and filters. Locate existing full-text rows by indexed literal name for updates, falling back to the previous scan for tokenless/missing names or lookup failure. Keep the existing schema and transactions.
HTTP tools taking over ten milliseconds allow socket polling before response encoding with a one-millisecond cooperative pause; fast tools can reply immediately, and individual CPU-bound phases remain cooperative.
Add cooperative checkpoints during cold file-cache fills and task-block parsing, allowing independent HTTP reads while these tools populate their caches. Warm file-cache hits keep their direct path. Recheck file fingerprints after a pause before publishing a cached value.

[0.3.3] - 2026-10-24

status reuses its index work while nothing it reads has changed. The note summaries and orphan names, with the sorted recent notes and the orphan list derived from them, are kept while the native notes/ listing, SQLite's data_version (another connection's commit) and total_changes() (this connection's own writes) are unchanged, so a note deleted outside folio still leaves status at once. The key also holds the connection's transaction count, so rows read inside a transaction that rolls back are not reused. A notes/ symlink the walk follows, or a failed query, turns the reuse off.
No index or file format change: 0.3.1, 0.3.2 and 0.3.3 processes share one store and index.

[0.3.2] - 2026-10-24

Skip the per-file census on idle ticks. Each 15 s tick compares one native metadata listing of notes/ and projects/ (size, mtime-ns and ctime-ns of every entry) and SQLite's data_version with the last complete census, and runs the full census only when something differs, another connection committed, or a retryable failure is pending. A listing is trusted only once its newest mtime and ctime are 2 s old, so writes inside one coarse timestamp granule cannot hide. A symlink the walk would follow (any in projects/, any not under a dot component in notes/), a metadata query that fails, or a listing line that does not parse as 7 fields disables the skip. On a 4,467-note corpus an idle tick drops from 216-611 ms of CPU to about 24 ms.
Yield every 32 files during a full census, so a large outside change no longer holds a shared HTTP server's only thread while it is reconciled.
Reuse parsed project files, the parsed inbox and buried-id scans while each file's stat signature (dev, inode, size, mtime-ns, ctime-ns) is unchanged. A file is cached only once its mtime and ctime are 2 s old; a recently written file is parsed on every call. tasks, projects and status no longer re-parse every project file on each call.
Answer task-notes from cached note frontmatter, keyed the same way, instead of parsing every note on each call (6.5 s on the corpus above). The answer is still computed from the files at call time.
No index or file format change: 0.3.1 and 0.3.2 processes share one store and index.

[0.3.1] - 2026-10-22

Recheck file existence inside census removal transactions and forget vanished failure entries. Require offline migration before the first upgraded server start.
Isolate startup/census failures per item, skip work another process already indexed, and rebuild documents without clearing the shared index. Add offline --migrate-index for staged upgrades.
Refresh derived indexes after releasing the file-write lock and preserve the original handler error if index maintenance fails.
Persist backlinks for notes and projects in the existing SQLite index. Refresh affected entries after writes, renames and project archival while preserving literal link matching and source order.
Build status note summaries and orphan detection from indexed metadata instead of loading every note body.
Detect external changes periodically in stdio mode as well as HTTP mode. Finish the initial index reconciliation before answering requests, and stop the stdio census when input closes.

[0.3.0] - 2026-10-16

Add shared MCP HTTP mode with a token-file bearer credential and an IPv4 loopback listener. Preserve stdio.
Deprecate the local note viewer: accept --web/--web-port with one stderr warning and ignore them.
Detect external edits incrementally without holding the note/project write lock during index maintenance. Refuse full index rebuilds over HTTP; keep stdio maintenance available.
Treat invalid crosslink targets as broken links and reject project names that escape their directory.
Serialize complete index transactions per connection, and report invalid batch-move entries without aborting later moves.

[0.2.14] - 2026-10-16

Fixed

Update sigil-json to 0.16.1 so encoding long Unicode strings takes linear time, preventing CPU stalls while serializing note responses.

[0.2.13] - 2026-10-01

Fixed

Concurrent writers no longer lose or tear notes. Two folio processes on one root (several MCP clients, or a restart overlapping the old process) could each read a note, change it and write it back, so one write silently replaced the other, and a reader could see a half-written file. Writes now take a cross-process lock (BEGIN IMMEDIATE on .folio-write-lock.db in the root) and replace files atomically through a temporary file and a rename. Measured: 2, 4 and 8 processes doing 20 appends each lost 1, 5 and 10 before, and 0 after; 6 writers plus a reader damaged 4 of 10 trials before, and 0 after. FOLIO_LOCK_TIMEOUT sets how long a writer waits.
A fresh root no longer kills processes that start together. Several processes creating the root's directories at once could fail with "already exists" and exit. Creating a directory another process just made is now fine. 160 concurrent starts lost 38 before and 0 after (test/test-startup-race.sh).
A tool refuses arguments it doesn't declare. Every tool schema is closed (30 of 30). An undeclared argument used to be ignored, which is how a misnamed mode or operation plus content on note-edit replaced a whole 245KB note with a few bytes while reporting success. It's now an error, and the note is untouched. inbox-add and task-add declare priority, source and ref.
note-edit keeps a note's title. note-create writes the title as the body's first heading, and replacing the body with content that had no heading dropped it. The existing heading now stays unless the new content starts with its own.

Changed

Built on sigil 0.22.12. sigil-lib and sigil-stdlib move from 0.21.0 to 0.22.12 for its build-cache fixes; the other dependencies take patch updates (sigil-mcp 0.18.2).

[0.2.11] - 2026-08-11

Fixed

An unknown argument is refused instead of ignored. folio --typo used to start the MCP server and exit 0, so a mistyped flag looked exactly like a successful run. Unknown arguments now exit 1 with a usage message naming what is actually valid, and --help / -h work with no environment configured at all (previously --help required FOLIO_ROOT).
--version and --help no longer bypass validation. They were scanned for across the whole argument list before validation ran, so folio migrate-buried --version printed a version and exited 0 — the same silent success this release exists to remove, reachable through the fix for it. The check is a property of what can reach it, not of the check itself.
The validator no longer disagrees with the code that reads the arguments. folio --log --web was accepted as "--log with the value --web", after which the port finder started an HTTP server nobody asked for and the logger wrote a file literally named --web, all at exit 0. A validator that blesses an invocation the program then reads differently is worse than no validator.
--web-port no longer fails at runtime. The port check called exact?, which is unbound in sigil: it compiled cleanly and raised on every real --web-port invocation. Caught by a test arm that runs the actual deployment command rather than a synthetic one.

Added

--stdio is accepted and ignored, as a documented compatibility no-op. It names the transport folio already uses, and it is a common MCP client convention.
test/test-cli-contract.sh, 23 arms, each verified individually falsifiable against a stubbed CLI. Some arms deliberately run live deployment invocations rather than defect cases; they are marked as such because that is what caught the exact? runtime failure, and they are the opposite of redundant.

Known

--log-level=trace is refused with a correction pointing at --log-level trace. The consumers match flag names exactly and never split on =, so accepting the joined spelling would start folio and silently ignore the flag. Accepting both spellings honestly requires folding the three argument parsers into one pass, which is tracked separately.
serve remains accepted. It was never a subcommand: there was no dispatch, and the old loop ignored unrecognised arguments, so folio serve has always worked by accident. Live deployments depend on it.

[0.2.10] - 2026-08-06

Fixed

A multi-line capture round-trips: an item's extent is SYNTACTIC, and the burial class is closed. A task is its checkbox header line — metadata at the end of that line — plus the run of following lines indented at least two columns past it (one blank line is allowed between body lines when bracketed by indented ones). Extent is decided by indentation alone, never by content: no heading, fence or hashtag heuristics anywhere, so a removal can only ever take lines indented under the item's own header, and unindented prose, headings and config fragments are untouchable by task operations by construction.

This ends the mechanism that buried at least 22 items between April and August 2026: the old writer appended {id: ...} after the whole text, a newline put it on the capture's LAST line, the line-oriented parser saw only the headless first line, and backfill-ids! then minted a phantom id onto it — one capture became a phantom head plus an invisible tail, while folio/status reported the inbox empty. Writers now put metadata on the header and indent the body; every mutation (complete, reopen, update, move, triage, sweep, clean) operates on whole blocks by their recorded line extents. Moves also now preserve completion — a completed task used to arrive reopened while still carrying its completed: date.

Buried items are reported loudly, and id assignment freezes around them. A new independent scanner — sharing no code with the parser, by design and by lesson — walks raw file text for t- ids and compares against what the parser actually produced. Anything written on disk but unreachable by every query is named, with its line, in folio/inbox and folio/status. backfill-ids! refuses to touch a file holding a buried id, so the phantom-mint path is closed from both ends. Ids inside terminated column-0 HTML comments are annotation and are not flagged; ids quoted inside a visible task's own text are that task's content, not a burial.
Rewrites that would destroy bytes now refuse instead. A header whose parse is lossy (stray braces around the metadata) loses part of the line on every re-serialize — completing one such task destroyed its tail, and a plain LISTING destroyed {braces} in text} via backfill (a defect that predates this release). Every in-place rewrite, move and triage now checks the header survives parse→serialize byte-identically and refuses by name when it does not; backfill skips such lines.
Text containing tool-call markup is refused at the door. </text>, <parameter name= and </parameter> can never be legitimate captured content — their presence means the client's tool call fell apart and its argument list leaked into a value (this buried two items live on 2026-08-06). All string arguments of inbox-add, task-add and task-update are checked; nothing is stored on refusal.

Added

folio/migrate-buried — explicit recovery of legacy buried items. Dry-run by default: prints per-id actions and a unified diff, writes nothing. It converts the two understood burial shapes (headless checkbox head with a trailing-metadata body; a bare prose block ending in an id line), REFUSES what it cannot convert without guessing — a bare-id phantom head above the tail (recovery is a human MERGE of two tasks), and tool-fragment shapes whose metadata does not close on its own line — and verifies every conversion with the independent scanner before accepting it. A conversion deletes nothing: lines are reindented and one metadata substring relocated, line count preserved exactly.

Compatibility

Files written by 0.2.10 remain readable by older binaries: headers are unchanged as task lines, and indented bodies read as inert prose. Older binaries cannot SEE bodies (they list the header line only) and must not be used to mutate a store containing multi-line items — their line-based removal would strand bodies. Upgrade the binary before writing.

[0.2.9] - 2026-08-05

Fixed

The note walk no longer has a size ceiling, and folio can start again. find-md-files-recursive folded each directory's entries with fold-right, which is not tail recursive — it burned one interpreter stack frame per file. The maximum size of a folio was therefore set by the interpreter's stack rather than by anything folio chose, and past roughly 1011 entries in a single directory the walk blew the stack outright.

Because every tool that enumerates notes starts at that walk, the blast radius was the whole server. A fresh folio serve could not finish starting — it died during index reconciliation, after logging Opened search index and before MCP server ready. In an already-running server, startup had succeeded back when the corpus was smaller, so the process stayed healthy while individual calls began to fail: note-links, status and note-rename stopped answering, and everything that addresses a note by path (note-read, note-create, note-patch, the task tools) kept working. That partition is what the defect looks like from outside.

The walk is now iterative, with an explicit worklist. Stack depth is the directory nesting depth — single digits — instead of the file count. Ordering is unchanged: directory-list order, depth-first, subdirectories expanded in place. Verified against a real corpus with all 2460 notes in one flat directory, 2.4x past the old ceiling, at no measurable cost (cold reindex 14.0s before, 14.2s after).

Measured, on a copy of a real vault: 1010 entries fine, 1012 fatal. Six empty notes containing no links at all were enough to cross it, and the same threshold held whichever six were added — it was the file count, not the content and not the link graph.

A tool that dies mid-call now says so instead of going silent. When a handler raised through the internal CPS frames of a higher-order stdlib procedure, the native backend mis-unwound it: the dispatcher's guard never ran, no JSON-RPC response was written at all, and the caller blocked until its idle timeout while the server stayed up and answered later calls.

Silence is the worst failure a caller can be handed — it is indistinguishable from slow and from succeeded, so the reasonable response is to retry, and a retry of a mutation whose disk write already landed double-applies. This was not hypothetical: a note-rename that never answered had already renamed the file and updated none of its crosslinks.

Every tool handler is now wrapped. Ordinary failures are re-raised unchanged, so they still arrive as a proper JSON-RPC error envelope; stack exhaustion — the one condition measured to be unserialisable — is returned as an explicit report that also warns the change may be partially applied. It is a known-list rather than a catch-all: an unmeasured condition keeps existing behaviour instead of getting a guess.

Known issues

note-rename is not atomic. It renames the file first, then rewrites crosslinks across referring files with no transaction and no rollback, so a failure partway through leaves the note renamed and some or all crosslinks stale — with no error if the failure was the silent kind described above. The walk fix removes the cause seen so far, but not the exposure. Tracked separately.

[0.2.7] - 2026-08-02

Fixed

Moving a task no longer renumbers it. Ids are preserved in every direction — inbox → project, project → inbox, project → project, and folio/inbox-triage. An id you hold before a move is still valid after it, so task-move → task-update <same-id> chains correctly and a triage plan built from an inbox dump keeps working once the items are routed.

This was never a design constraint. Ids are globally unique random hex with no per-project id space, so nothing required a new one on move. project-add-task! simply called generate-task-id unconditionally and ignored any id handed to it, while move-task-in-store! stripped the id out on the way in. The asymmetry gave it away as an oversight: project → inbox passed metadata through untouched, and only inbox → project destroyed the id.

A task can no longer end up carrying two id entries. Moving a task from a project back to the inbox prepended a fresh id without removing the existing one, leaving both on the line; lookups silently resolved the first.

Added

folio/task-move-batch — move many tasks in one call, either {ids: [...], project: "x"} for a shared target or {moves: [{id, project}, ...]} to fan a single call out across many projects. An entry with no project moves that task to the inbox.

Returns a result line per id so partial failures are visible rather than swallowed, and the header counts successes rather than attempts. Because ids are now stable, the reported id is the one the task landed under.

Triaging 227 inbox items on 2026-08-02 cost 226 individual round-trips, which is a large part of why that inbox went untriaged for four months.

Changed

Toolchain moved to sigil 0.18 (sigil ^0.18, sigil-run ^0.18.0, sigil-http ^0.18.0, sigil-sxml ^0.15.0), with runtime core resolving to 0.18.1. sigil-test / sigil-test-runner remain pinned at ^0.17 (0.17.16): bumping them aborts the install because sigil-http, sigil-tls, sigil-crypto and sigil-web-styles each declare a dev-dependency on sigil-test ^0.17 and the resolver unifies across the graph. That affects the test harness only, not the shipped runtime, and clears once those four repos move their dev-dep.

Known issues

A capture containing newlines is still stored in a shape folio cannot read back. folio/inbox-add accepts multi-line text, but the {id: ...} metadata is appended to the END of the text, so on a multi-line capture it lands on the item's last line. The parser sees only the first line, which has no id, and backfill-ids! then mints a fresh id onto it — the real item and its metadata become unreachable and a phantom one-line duplicate appears in its place. Six items were hidden this way between April and August 2026.

This is not fixed in 0.2.7. A block-parsing fix was written and withdrawn: it cured the burial but introduced worse defects, because it inferred where an item ends and then let destructive operations act on that inference. The redesign makes an item's extent syntactic rather than inferred.

Until it lands, capture multi-line content as a note and reference it from a single-line inbox item, rather than putting the body in the item itself.