← Versions 1.0.0 In progress

1.0.0

Two backlogs: the release scope, and what the work turned up.

Backlog 1 — release scope

Planned work. An item is only here if it loses data, breaks a promise on a public surface, or stops a stranger installing and running the thing. A ticket that reaches Done carries the version it shipped in.

KeySummaryComponentStatusVersionBlocked by
SAPE-1Build identity: version embedded, version command, product version in handshakeserverDone1.0.0—
SAPE-2Versioning and compatibility policydocsDone1.0.0—
SAPE-3Prebuilt binaries and a published container imagereleaseIn progress—a tag
SAPE-4Tag-driven release workflow for the serverreleaseIn progress—a tag
SAPE-5Install path and quickstartdocsTo do—SAPE-3
SAPE-6Upgrade rehearsal: one build writes, the next reads it all backserverDone1.0.0—
SAPE-7Config reload, led by partial reloadserverDone1.0.0—
SAPE-8Read an operation's cost envelope before trusting itserverDone1.0.0—
SAPE-9Name collision: operation names get a namespaceserverDone1.0.0—
SAPE-10Sign and verify an operation bundleserverDone1.0.0—
SAPE-11List the external operations installed on a serverserverDone1.0.0—
SAPE-12One worked external operation, published as a challengedocsIn progress—a stranger, for its first two criteria
SAPE-13An artifact describing the shape of a request bodyprotocolDone1.0.0—
SAPE-14Declare for collectionsserverDone1.0.0—
SAPE-15learn.sapedb.comdocsIn progress—hosting and DNS
SAPE-16sapedb.comdocsIn progress—SAPE-15, SAPE-5
SAPE-17The on-disk format tag and the key labels say sapedbserverDone1.0.0—
SAPE-18Reads share a database instead of queueing behind each otherserverDone1.0.0—
SAPE-19Declare an operation against a running daemon — frame 13protocolDone1.0.0—
SAPE-20Composed operations, with a ceiling readable at any depthserverDone1.0.0—
SAPE-21Scopes travel the wire as a signed grantserverDone1.0.0—
SAPE-22A count must declare how far it walksserverDone1.0.0—
SAPE-23InvokeVersion, so an older declaration is reachableprotocolDone1.0.0—
SAPE-24Three clients, each run against a real daemonclientsDone1.0.0—
SAPE-25Desktop workbench: connections, catalogue, run, shell, compose, declaredesktopDone1.0.0—
SAPE-26Apply a change: replay a log entry into a databaseserverDone1.0.0—
SAPE-27Follower mode: a daemon that subscribes, applies, and refuses writesserverDone1.0.0—
SAPE-28Check a signed bundle, then install what it declaresserverDone1.0.0—
SAPE-29Decide the type list, onceserverTo do—a product decision — dossier ready
SAPE-30An integer that is the integer you sentserverTo do—SAPE-29
SAPE-31A type for bytes, because a string silently is not oneserverTo do—SAPE-29
SAPE-32deleteRange — remove a stretch of keys, with a ceilingserverDone1.0.0—
SAPE-33concatRange — join a stretch of values without shipping themserverTo do—SAPE-31
SAPE-34hashRange — a digest of a stretch of keys, without moving itserverDone1.0.0—
SAPE-35Decide what the operator's shell owes, separatelyserverTo do—a product decision
SAPE-36Measure this store under a small VPS's limitsreleaseDone1.0.0—
SAPE-37Exact nearest-neighbour search over a declared vector fieldserverIn progress——
SAPE-38Approximate vector search, and how to be honest that it is approximateserverTo do—a product decision
SAPE-39Store a vector as a vector, not as five times its size in textserverTo do—SAPE-37

25 done, 6 in progress, 8 to do. For a few hours this page said every remaining ticket was waiting on a person rather than on work. That stopped being true when the owner asked for an explicit type system and put it in 1.0.0 rather than a later version, and the sentence is replaced rather than quietly edited because the change of shape is the news.

SAPE-36 is on this list late, and that is the point of it being here. The owner asked for the store to be measured under a small VPS's limits; it was built, it found two defects, and for a while it existed only as commits — nothing on this board said it had happened. A board that carries only what fits a scope written in advance stops describing the work, and somebody reading it concludes nothing was done. The rule now is that a thing is updated here as it lands, not gathered up afterwards. ISS-40 arrived the same way.

Three of the eight to do are the type system — SAPE-29 decides the list, SAPE-30 and SAPE-31 build the two entries that are measured rather than argued for. Of the three engine primitives, two have shipped and the third is no longer needed for anything anybody asked for. SAPE-34 and SAPE-32 were together the whole requirement for the ten-megabyte file split across thousands of rows, and that use is now served: the rows stay where they are, deleteRange clears a stretch with a ceiling, and hashRange answers the one question that could not be answered without moving everything. SAPE-33 is what is left, it was never required, and it still waits on a size ceiling — the one thing that has not moved, because its output is the only one of the three that grows with its input. SAPE-35 asks a question rather than proposing a change: the operator's shell inherited the application's rules by default rather than by decision, and the answer may well be that they are the right rules — but "we thought about the operator and concluded the same" and "nobody asked" produce identical code and different futures. The sixth, SAPE-5, still waits on a release being cut. The last two, SAPE-38 and SAPE-39, arrived with vectors.

What shipping SAPE-34 and SAPE-32 measured, beyond that they work. Three of their guards are worth more than the features. The first is a mutation that stays green on purpose: counting the ceiling per underlying call instead of per run is invisible to a single-range test, and goes red only against a collection split across partitions. On a one-partition store the two counters cannot be told apart — so the guard that would catch W7's shape has to be built to span a boundary, and a green result anywhere else proves nothing about it. The second is something the ticket did not foresee. The operator shell caps a typed limit at 1000 before validation, which is right for a scan, because a capped scan still answers. A digest does not answer: it refuses. A ten-megabyte file in five thousand rows — the exact case this command exists to check — would have refused every time, on a limit nobody chose. A typed hash is asked for its limit instead, and the comment claiming the cap meant those rules could never fire has been corrected rather than left standing where it reads as an instruction.

The third is a guard that failed in the shape of diligence. SAPE-32's rollup assertion compared a deleteRange against the same rows deleted one at a time — a real comparison, run against a real second store. Removing the line that decrements a rollup on delete left it green, because the mutation breaks both paths identically and two wrong answers agreed with each other. The fix is an absolute check: the rollup recomputed by walking the rows that are actually still there. It is the rule about a guard not reading its expectation from the thing it guards, wearing a disguise — nothing here looked lazy, and the comparison was still circular.

And one line moved before the ticket that exists to decide it. Access.Kind carried a stated rule: nothing writes; a change to a production database should be something somebody wrote down, reviewed and can run again. SAPE-32's shell section overturns it on purpose, for the operator holding the connection at two in the morning clearing rows that should not be there. The comment keeps the old rule in view rather than deleting it, and the reversal is defensible — a typed delete is still the operation it would have to be declared as, held to the same validation and logged under the operator's name. But SAPE-35 is the ticket for deciding what the shell owes, and it is still open. Whoever answers it should know they are answering about a shell that already writes.

Those two primitives exist because a framing on this page was wrong. Asked whether a batch could delete thousands of rows atomically, the answer here was no, and the reason given was that a batch's shape is fixed when declared. That describes how the driver models a batch and says nothing about what the engine may do. The promise this project is built on — cost declared, no expressions — constrains the layer a client speaks to, not the storage underneath it. The proof was already on this board: a rollup is the engine computing a count and a sum and maintaining them incrementally, while the driver only ever lets somebody declare that rollup. Engine computes, driver declares, promise intact. Any primitive that can be offered on those terms is available on those terms. Of the five in progress, four want a tag or a DNS record and the fifth wants a stranger.

The type system arrived as a question and turned into a defect. Asked what types sapedb supports, the answer was four — string, number, bool, any — and measuring that answer found ISS-35: an integer above 253 is stored as a different integer, silently, and a string given the byte 0xFF stores U+FFFD instead, also silently. Both answer changed 1. That is why two of the three tickets are not a matter of taste.

SAPE-9 has its answer, it is not the one this page recommended, and it has shipped. The dossier argued for flat names; the owner chose namespaces. The shape: namespace:name, at most one colon, and no colon at all is legal — it means the unnamed namespace, so every flat name in existence keeps working untouched. A named namespace is claimed by whoever declares into it first and refuses everybody else afterwards; the unnamed one is never claimed, which is today's behaviour, now written down honestly as the namespace nobody owns.

Measured end to end against a binary built from the merged tree, not from a transcript: two authors seal bundles declaring the same namespaced name; the first claims the namespace for its signing key; the second is refused, naming both keys, and its own collection is never created. A flat name declared afterwards by a different actor through plain apply is still accepted — which is the whole reason nobody has to change anything. The 8,349 passing tests are exactly 8,321 + 16 + 12: two features built in parallel by agents that could not see each other, and neither cost the other a test.

SAPE-12 is the one ticket left that no amount of building finishes. Its first two criteria are a stranger writes a working module from the published material and the list of questions they had to ask the authors is empty. The tooling they would need now exists — keygen, seal, verify, install — and the worked module and its documentation are being built. The measurement still needs somebody who did not write it.

Why it could not wait. TestAnOperationNameMayHoldAnySeparatorAName already measured that every separator is a legal operation name today — acme:orders.recent among them — and COMPATIBILITY.md section 3 forbids tightening a rule inside 1.x. A namespace that misses the tag can never be added at all. That test was written to record a curiosity; it turned out to be the deadline.

This table has said Done for tickets that were not, more than once, and every time it was caught the same way: by reading what the ticket asks for rather than what the row says. SAPE-15 and SAPE-16 had said In progress on their own pages the whole time. SAPE-4 was marked Done here for about twenty minutes; four of its five criteria need a tag that has actually been pushed, including the one it calls the bar — an artefact downloaded onto a clean machine and executed there. ISS-4 was marked Done on two of its six call sites and put back until all four readers had one.

Vectors are in 1.0.0, and they arrived as two tickets on purpose. The owner decided that 1.0.0 supports vector search. Measured first: the engine had no vector code at all. The work is split because the two halves of vector search fail in different ways. SAPE-37 is exact search — every row in the walked range compared, the true top-k returned, cost declared up front and the answer correct. It keeps this product's promise exactly as hashRange does, and it is being built. SAPE-38 is approximate search, and it breaks a different promise than cost: in the owner's own measurements a configuration reporting 97.75% mean recall returned four queries in two hundred at 0%, and a 0% answer looks exactly like a 100% one. That is the shape this board has refused three times today. It needs a decision about how a result that may be wrong is shown honestly — and a measurement, running now, of how far exact search goes before approximate search is needed at all.

The owner then sharpened it: a vector store that can serve RAG. That adds needs a bare nearest-neighbour search does not have, and measuring one of them opened a third ticket. As JSON text — the only way a body stores a vector today — an embedding is 5.2 times its float32 size: a million chunks at 1536 dimensions is 30 GiB against 5.7 GiB, for the vectors alone, and every search must parse 1536 numbers out of text per row. That is SAPE-39. It waits for SAPE-37 on purpose: exact search is being built over the slow correct form, its tests compute the answer from outside the package, and those tests are what make changing the storage underneath a safe change rather than a guess.

Backlog 2 — issues found while working

Opened by the work in Backlog 1, not planned before it. Each one is triaged once: Fix in 1.0.0 only if it loses data, breaks a public promise, or blocks installing and running; otherwise Defer, and it goes to planning for the next version. The triage column is the decision, not a guess at how bad it feels.

KeySummaryFound whileTriageStatusVersion
ISS-1The covering index is built, decoded per entry, then discardedSAPE-20DeferOpen—
ISS-2Fixture copies kept identical by hand; nothing compares themSAPE-19DeferOpen—
ISS-3The fixture covers 9 of 14 frame typesSAPE-13DeferOpen—
ISS-4The ErrFormat refusal path has no test at allSAPE-6Fix in 1.0.0Done1.0.0
ISS-5A composed operation's rows come back flat and unlabelledSAPE-20DeferOpen—
ISS-6An encryption test is flaky: it searches ciphertext for a 3-character stringSAPE-17Defer — overriddenDone1.0.0
ISS-7internal/cli's open() leaks partition files, as Server.Close didSAPE-19Defer — overriddenDone1.0.0
ISS-8Two write handlers in one file roll back differentlySAPE-19DeferOpen—
ISS-9A read-only composed operation takes the write lockSAPE-20Defer — overriddenDone1.0.0
ISS-10A composed operation must name a collection it may never touchSAPE-20DeferOpen—
ISS-11A grant has no expiry and cannot be revoked short of rotating the server secretSAPE-21Fix in 1.0.0Done1.0.0
ISS-12The TypeScript client cannot present a grant, so it cannot reach a scoped operationSAPE-21Fix in 1.0.0Done1.0.0
ISS-13Declaring a collection is not recorded against anybodySAPE-19DeferOpen—
ISS-14The old product name survives in three production constants, assembled byte by byteSAPE-17DeferOpen—
ISS-15The release plan went stale the same day it was writtenSAPE-2—Done1.0.0
ISS-16The TypeScript client ignores the product version the daemon now sendsSAPE-1DeferOpen—
ISS-17sapedbd has no version command; it only says so in a log lineSAPE-1DeferOpen—
ISS-18A linker stamp aimed at a symbol that does not exist is accepted in silenceSAPE-1Defer — overriddenDone1.0.0
ISS-19The worked example declares no projection, so it teaches the untyped pathSAPE-13Defer — overriddenDone1.0.0
ISS-20A client derives shapes from a schema file on disk, not from the server's catalogueSAPE-13DeferDone1.0.0
ISS-21The most declaration-shaped refusal of all reads as "failed"SAPE-14Fix in 1.0.0Done1.0.0
ISS-22Anyone holding a connection string can read the entire change logSAPE-26Needs a decisionOpen—
ISS-23No operator can cap log retention; the disk fills while everything looks healthySAPE-26DeferOpen—
ISS-24The PHP client's pinned fixture predated the wire it speaks, and its refresh command 404sSAPE-24Fix in 1.0.0Done1.0.0
ISS-25The PHP client had no CI, so a skipped test and a passing test read the sameSAPE-24Fix in 1.0.0Done1.0.0
ISS-26Reading the catalogue is a write, so the operator shell cannot be pointed at a followerSAPE-27DeferOpen—
ISS-27A valid signature for a database that never existed brings it into existenceSAPE-14DeferOpen—
ISS-28Both clients have CI; the database at the centre of them does notSAPE-3Fix in 1.0.0Done1.0.0
ISS-29SAPE-18's gate measures how many cores the machine has, not whether reads shareISS-28Fix in 1.0.0Done1.0.0
ISS-30The workbench cannot run the reads a follower would allowSAPE-27DeferOpen—
ISS-31Integration is checked when the client moves, never when the server doesISS-21DeferOpen—
ISS-32A collection can be dropped; an operation can never be removedSAPE-9Needs a decisionOpen—
ISS-33The command line cannot invoke a declared operationSAPE-12Fix in 1.0.0Done1.0.0
ISS-34Installing a signed bundle means stopping the databaseISS-33DeferOpen—
ISS-35A number above 253 is stored as a different numbertype-system planningFix in 1.0.0Done1.0.0
ISS-36The shell's line limit answers in Go's words, not the product'sISS-35DeferOpen—
ISS-37The 16 MiB cap refuses an answer the server has already built in memorythe first benchmarkFix in 1.0.0Done1.0.0
ISS-38An answer that does not fit and a server that died both arrive as EOFthe first benchmarkFix in 1.0.0Done1.0.0
ISS-39A two-value range over a descending bool index can never return a rowdebt-list surveyNeeds a decisionOpen—
ISS-40The worked-example guard cannot see the page it is aboutSAPE-12DeferHalf closed—

Four more closed, all of them triaged Defer, all overridden on purpose. The owner's position is that the core engine is not finished, and these were four of the unfinished parts: ISS-9 (a read-only composed operation took the write lock), ISS-7 (the command line leaked partition files), ISS-18 (a linker stamp at a missing symbol was accepted in silence) and ISS-6 (an encryption test that went red at random). None needed a product decision; each had a fix already demonstrated elsewhere in the same repository.

Three of the four tickets were wrong about themselves, and the corrections are the news. ISS-7 said unreachable today: a test written against the unfixed build reproduced it immediately with vfs.ErrLocked on a .part file. “One command is one process” is a property of cmd/sapedb, not of open() — two calls in one process are enough, and this repository's own tests already do that. The only reason nobody had hit it is that no CLI test had declared a partitioned collection, which apply installs happily. ISS-18 said three spellings; there are four, and the fourth is in README.md — a go build -ldflags line handed to a stranger to paste. ISS-9 was deferred because the fix “represents a schema decision”; the fix that was actually available adds nothing to Operation, to the wire, or to a dump.

And the guard everybody trusted was measured rather than argued about. ISS-18's existing check was run against a mutated tree and stayed green for three separate holes: a second misspelled -X beside the correct one, a recipe that stops passing the stamp while still defining it, and a wrong spelling in README.md — which it never read at all. One of those was found by accident, and the first replacement missed it too.

ISS-6 was arithmetic all along, and the fix is now self-guarding. Two of its six needles were three bytes; in a 49,152-byte image that predicts 11.7 chance hits in 2000 runs, and the measurement was 11. The short needles were not deleted — "ann" was an indexed value and "s07" a unique key, the two most interesting things to find in the open. The documents' values were lengthened instead, so the same two things are still asserted absent, and the test now computes each needle's collision probability before it searches and refuses a needle list that spends more than 1e-8 per run. A short needle added later fails on the first run by name, with the arithmetic in the message, instead of once in a few hundred. Measured after the fix: 0 in 2000, and 0 in 10,000.

How an issue gets triaged

One question, asked once, and written down: does it lose data, break a promise on a public surface, or stop somebody installing and running the thing? Twelve of forty answer yes — counted, not remembered, because this page said "nine" once while it was eight, and nobody had added them up. All twelve are closed. The last was ISS-35 — a number above 253 stored as a different number, silently: sending 9007199254740993 stored 9007199254740992 and answered changed 1. It is refused now on every door that takes a number from outside, and it stayed listed as half shipped for the hours between the two halves rather than as done, because a defect closed on one path and open on another is exactly the shape somebody reads as finished. The ninth of them, ISS-33, was opened after the other eight were shut, by following SAPE-12's worked example from a cold start: the module installed, and then the shell had no way to call anything it had just installed. A database whose whole argument is that the only interface is a declared operation could not ship a command line that called none. It now has one, in the shell and as a command a script can branch on — the piped form returned success whether the operation ran or was refused, which is the silent failure this project spends its documentation arguing against. Closing it opened ISS-34, which is the next thing a stranger hits and is a better shape than the one it replaced: the path with the signature, the trust list and the all-or-nothing transaction on it is the one path with no wire frame, so accepting a signed module is downtime. That is a limit, not a defect, and it is deferred — but a reader who notices it should find it written down already.

Two of those eleven arrived together, from the first time this store was measured under a machine's limits rather than a laptop's — and both are now closed. ISS-37 is the one that matters: on 512 MiB with swap disabled, steady-state memory for inserts, scans and deletes never left 16–20 MiB on any of the three profiles — and then a single read asking for about 88 MiB of rows took the process to 352 MiB and it was OOM-killed, exit 137. The 16 MiB frame cap did refuse smaller versions of that read, which is why SAPE-31 was corrected; but it refuses by measuring a payload that has already been built, so it is a guard in front of the wall that stops nobody reaching the wall. ISS-38 is the half of it a caller sees: that refusal and a dead server both arrived as a bare EOF. The store is not what fills a small machine. One unbounded read is.

What closing them measured. A byte budget is now spent while rows are accumulated, so the answer is refused before it exists: the same 49 MiB reply that cost 254 MiB of live heap to build now costs 28 MiB and is never built. The refusal carries too_large, and a test runs a second call on the same connection — no redial is needed to tell a refusal from a dead server, which was the whole of ISS-38.

And a mutation that passed is the most useful thing in that work. Removing the server's budget entirely left the wire test green, because a late length check still caught the finished payload and still sent the right code. The client was being told the truth about a server that had just built the whole answer — precisely the defect ISS-37 is about, invisible to the test written for it. The fix was to assert that the refusal names the rows it reached, which only the budget can know. It is recorded here because nobody would have looked for it: the test was green, the feature worked, and the guard was watching the wrong end.

Closing ISS-35 turned up something that was never about rounding. bundle.Message is computed over the declarations as parsed, and 9007199254740992 and 9007199254740993 parse to the same float64 — so an author's signature over one verifies a file edited to say the other. Measured with two binaries: seal a draft, edit the signed file, install it, and the server reports it trusted. The signature proved who wrote the declaration and never proved which number it carried. It is pinned now by TestASignatureNeverProtectedTheNumber, and it was not introduced by this work — it was there to be found.

The same pass found the shell handing an operator a rounded declaration to paste into a schema: typing a key of 9007199254740993 and pressing declare gave back "value": 9007199254740992. A rounding, packaged as a source file. And two of its own mutations came back green on the first pass, because one check ran before the other and made the second decorative — found by mutating, not by reading, and the report says so rather than listing a pass.

ISS-35 is the one with a deadline, and the deadline is not about urgency. SAPE-2's policy lets a 1.x loosen a rule and forbids it from tightening one. Refusing a number that cannot round-trip is a tightening, so it can be introduced before the tag and never after; carrying integers exactly is a loosening and could wait. The question is therefore not which fix is better but which one has a deadline. If 1.0.0 ships without the refusal, silent rounding becomes a promise this project has to keep. ISS-39 has the identical shape and was found the same way, by measuring rather than reading: a two-value range over a descending bool index is accepted and returns nothing, because the guard that decides whether a range runs backwards reads the two values and the encoder that orders them reads the direction. Correcting it refuses a declaration that is accepted today, which is a tightening, which means before the tag or never. Two further issues are not mine to answer at all: ISS-22, a security posture, and ISS-32, which the namespace decision half-answered — it settles what a name means, not whether a declaration can ever be withdrawn. All of them freeze at the tag.

The rule also has to stop things that sound like defects. One report said the operator shell silently swallows the catalogue error at startup, which is literally true. Reading the surrounding code showed the discard is deliberate and explained — it feeds tab completion, and guessing names would be worse than silence — while ls, in the same file, reports the refusal properly. No ticket was opened. A rule that only ever adds is not a rule.

ISS-12 is the cautionary one. It sat here marked open after the work had been done, and was then used as evidence — twice in one sitting — to write a public claim that was false, the second time while correcting the first. A ticket is a record of what somebody found on a day. It is not a measurement of what is true now.

ISS-29 is the best thing on this page. It was found by ISS-28 within an hour of CI existing: a gate guarding a Done ticket had been measuring the number of cores in the machine and reporting the answer as a verdict about locks. The replacement counts how many reads are inside the database at once — an exclusive lock cannot reach two on any number of cores — and on the very runner that had been failing, it found four, in three milliseconds. The code had been sharing all along. Only the gate could not see it.

ISS-21 produced the other thing worth keeping. Two repositories had independently written a test that pinned the old code and said in its own comment that it would go red the day the server gave that error a name. Both fired, hours apart, neither knowing about the other. Pinning a value you expect to change is how you are told when it changes; the alternative is a comment that quietly stops being true.

What 1.0.0 freezes

A version number here is a promise that cannot be withdrawn. From the tag onwards these five surfaces are fixed: the on-disk format, the wire protocol (frames 1…13 never change role; fields may be added, never renamed or removed), the meaning of a declaration, the public API, and — as of SAPE-9 — the name grammar. It does not promise performance, the ordering of reads against writes, the file layout inside a partition, or anything under internal/.

That is now written into the repository as COMPATIBILITY.md (SAPE-2), with a test that opens every file the document cites and another that pins all fourteen frame numbers by hand. Writing it found a gap: pager.Magic was pinned as a literal and pager.Format was not, so changing the one field that decides whether this build may read a file at all left the whole suite green.

Frame 14 is now spent: SAPE-14 took it for establish. The next frame anyone adds starts at 15. The public Go surface is 40 names and has not moved since a grant grew an expiry — the bundle signing added in SAPE-10 lives entirely under internal/.