← 1.0.0 scope SAPE-12

One worked external operation, published as a challenge to somebody outside the project

Status
In progress
Component
docs
Priority
Medium — the acceptance test for the whole external-operations group
Blocked by
SAPE-7, SAPE-10, SAPE-14
Waiting on
a stranger, for criteria 1 and 2
Blocks
—

Description

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.

Revised 2026-09-20 — the worked example is a module, not a verb

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.

Why now

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.html contains 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 now KindDeclaration bundles plus SAPE-14's collection-over-the-wire, not a binary runtime.

Where the six criteria stand, measured 2026-09-22

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 asksNow
1A stranger writes a working module from the published materialNot met, and unreachable from inside.
2They asked the authors nothing the documentation should have answeredNot met. Six such questions were found and removed — see below.
3Built, signed and installed by the commands on the page, exactly as writtenHolds now, did not before.
4Cost envelope readable before installation, and matching what it doesHolds now. The second half shipped in 982bda8.
5Every read declares a projection; a client types it without a fallbackHolds for the worked module. Not for examples/ledger — that is ISS-19.
6The three sections carry prose, every command run against a real daemonHolds now.

Criterion 4: what was actually missing, and what closed it

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: six questions a stranger would have had to ask

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:

  1. sapedb seal module.json … — the file was never copied into the working directory. The CI job does it silently; the page did not.
  2. node bin/sapedb-types.mjs examples/library/module.json — resolves in neither repository: the binary is in one, the module in the other.
  3. sapedb verify out2.bundle.json — the page never creates out2.bundle.json; the block that made it was dropped when the page was published.
  4. An install shown failing on a declaration error actually fails on SAPEDB_SECRET is not set — the export came one block later.
  5. shell 127.0.0.1:7455 — nothing is listening; the page never starts sapedbd.
  6. 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.

What still blocks criterion 1, and it is not documentation

@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.

Acceptance criteria

  1. Somebody outside the project writes a working external operation module using only the published material, and it installs and runs on a server they set up themselves, with none of its collections pre-declared. This is the criterion.
  2. They did not ask the authors a question that the documentation should have answered. Every such question is recorded, and the page is not done while the list is non-empty.
  3. The worked example is built, signed and installed by the commands on the page, exactly as written, on a machine that is not the author's.
  4. Its cost envelope is readable before installation and matches what it does when it runs — SAPE-8's measurement, applied to this operation.
  5. Every operation in the module that reads declares a 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.
  6. The three needs the feature sections on 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.

Out of scope

What is measured now, and what still is not

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.