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

Status

To do

Component

docs

Priority

Medium — the acceptance test for the whole external-operations group

Blocked by

SAPE-7, SAPE-10, SAPE-14

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.

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

• A gallery of examples, or a directory of community operations. One that demonstrably works, not a collection.
• An SDK, scaffolding tool, or project template. If the module needs a generator to be writable, the interface is the thing to fix.
• Judging, hosting, or promoting submissions. "Challenge" here means the measurement is a stranger succeeding, not that there is a competition to administer.
• Making the example useful in production. It exists to be read.
• Any form of the other two shapes from 0071 — a single missing operation, or a 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.