Write one external operation end to end — declarations, signing, install, invocation — and publish it with the documentation somebody outside the project needs to write a second one. Then find out whether they can, by having somebody do it.
pipelines/tasks/0071 asked the user what an external operation is for, and got
three answers: (1) one operation sapedb is missing, (2) several operations folded into one —
function and procedure — and (3) one operation that solves a whole textbook
problem end to end, through the shapes it publishes. Shape (3) is the one that best exercises the whole
group, and it is not a single operation: it needs its own collections, indexes and
rollups (storage), its own operations (vocabulary), and — per SAPE-13's shape
rule — projections declared on every operation that reads, so a client can derive a typed
surface from it. The worked example for this ticket should be built at that scale: a small but complete
business module, not one missing verb.
This is also why SAPE-14 is now a blocker that did not exist when this ticket was written: a module bundle cannot install its own storage into a database that does not already have it, until collections can be declared over the wire. The old acceptance criteria assumed installing an operation was enough; installing a module needs both halves.
The external-operations answer to "what if the operation you need does not exist" is only true if somebody outside the project can supply one — and, per the revision above, "supply one" now has to mean a whole module for the hardest of the three shapes the user actually asked for, not the easiest one. Until that has happened once, the feature is a claim. It also fixes the published shape of a bundle at the same moment the rest of it freezes: the declaration layout, the signing step and the install sequence are what every future author copies, and moving them after the first one exists breaks that person's work.
Measured 2026-09-20. The page is already allocated and deliberately empty:projects/sapedb-site/learn/external-operations.htmlcontains zero<pre>blocks — it is the only one of the twelve learn pages with none — and is marked not written in the site navigation. Its own text says "Nothing here can be written until external operations land … There is no prose, because prose about a feature that does not exist is a promise, and this project does not make those." Three sections inside it are tagged needs the feature. This ticket is what turns those three tags into prose — and, per the revision above, the feature it is waiting for is nowKindDeclarationbundles plus SAPE-14's collection-over-the-wire, not a binary runtime.
This ticket is In progress and stays there, because criteria 1 and 2 need somebody outside the project and no amount of building reaches them. What changed is the other four, and they changed without this page saying so — which is the same defect this board keeps finding elsewhere, so it is recorded here rather than quietly fixed.
| # | What it asks | Now |
|---|---|---|
| 1 | A stranger writes a working module from the published material | Not met, and unreachable from inside. |
| 2 | They asked the authors nothing the documentation should have answered | Not met. Six such questions were found and removed — see below. |
| 3 | Built, signed and installed by the commands on the page, exactly as written | Holds now, did not before. |
| 4 | Cost envelope readable before installation, and matching what it does | Holds now. The second half shipped in 982bda8. |
| 5 | Every read declares a projection; a client types it without a fallback | Holds for the worked module. Not for examples/ledger — that is ISS-19. |
| 6 | The three sections carry prose, every command run against a real daemon | Holds now. |
The half that matched what it does always held, and its guard is real — deleting a
projection from the module makes it fail, naming the fields that escape. The half that
said readable before installation did not: sapedb verify printed what a
bundle declares and no envelope, and envelopeOf was an unexported method on a live
*Store. The only way to read an operation's cost was to install it first, which is
backwards — the envelope exists so somebody can decide before running it.
sapedb verify -envelopes now reads it out of the file. The thing that makes it a real
answer rather than a second opinion: one derivation, two entry points.
EnvelopeOf takes the operation and a lookup; Store.envelopeOf and the bundle
reader both call it. Two implementations would be two numbers that can drift, and the whole point of
this criterion is that the number you decide on is the number you get afterwards. The test is an
equality: it reads every envelope out of the file with no daemon and no database in
existence, installs the same module over the wire, reads them back from the catalogue, and
compares field for field across all nine operations.
A composed operation's envelope still cannot be read before installation, and it refuses rather than guessing. A reference inside a bundle can only name a declaration the receiving store holds — a bundle's own operations carry no version to be named by. Three tempting guesses are written into the code with why each is worse.
Criterion 2 is not done while the list is non-empty, so the list is the useful artefact even before a stranger exists. Following the published page verbatim, these six commands did not run as written, and all six are now fixed:
sapedb seal module.json … — the file was never copied into the working
directory. The CI job does it silently; the page did not.node bin/sapedb-types.mjs examples/library/module.json — resolves in
neither repository: the binary is in one, the module in the other.sapedb verify out2.bundle.json — the page never creates
out2.bundle.json; the block that made it was dropped when the page was published.install shown failing on a declaration error actually fails on
SAPEDB_SECRET is not set — the export came one block later.shell 127.0.0.1:7455 — nothing is listening; the page never starts
sapedbd.python3 -u mutate.py no-projection — no such script exists, in the
tree or anywhere in its history.Plus a preamble claiming “macOS 15 (darwin 25.3.0)” — darwin 25.3.0 is macOS 26.3.1 — on a page whose own rule is that nothing on it is reconstructed, elided or tidied.
@ecosy/sapedb is not published to npm — npm view
returns 404. Criterion 5 says a client generates a typed surface; the only client that does is
unobtainable to anybody who has not been handed the repository. A stranger cannot satisfy criterion 1
while that is true, however good the page gets. That is a publish, and it is the owner's.
projection, and a client generates
a typed surface from it without falling back to Record<string, unknown> — the
positive case for the rule SAPE-13 writes down and
ISS-19 reports the fixture failing today.learn/external-operations.html carry prose, and every command shown on the page was run
against a real daemon, per the site's own rule.function/procedure composed from a few. Those are simpler than the module
shape and do not need a new worked example to prove the mechanism works; the module is chosen because
it is the hardest case, not because the others do not matter.
Criterion 3 is met and is now re-measured on every push. .github/workflows/worked-example.yml
runs the documented sequence on a cold ubuntu-latest runner — a machine that is not the
author's — and asserts 94 things about it: keygen, seal, verify
refused with no trust list and refused when tampered and refused for a stranger's key and green when
trusted, install into a directory that does not exist, a real sapedbd, then all
nine of the module's operations invoked for real. The runner reported checks: 94, failures: 0,
the same 94 the same script produces on the author's macOS — so the BSD-versus-GNU difference between the
two machines changed no assertion.
The job also holds a floor over its own assertion count, because failures: 0 is exactly what
a run that did nothing prints.
Criterion 4 is met in its harder half and not in its easier one. That the envelope matches what the
operations do is measured in both directions. That it is readable before installation is not: the
envelope is derived inside a store, and a bundle nobody has installed is not in one, so the only true
pre-install read is to install it somewhere disposable first. Criterion 5 is met for every document read —
three reads, three named-field rows, no Record<string, unknown> — with one rollup still
emitting the fallback, because the generator answers totals before it looks at projections.
Criterion 6's prose is written and applied.
Criteria 1 and 2 are not met and cannot be met from inside the project. They are a stranger writing a working module from the published material, and the list of questions they had to ask being empty. Everything a stranger would need now exists and is exercised on every push. Whether it is enough is a measurement only somebody who did not write it can take.