The Gifts — a developer's guide

What a gift is

A gift is the smallest thing Loop MMT ships to the world: a single file, zero dependencies, MIT-licensed, that runs both as a command-line tool and as a browser-attachable pure function. It does one job, states plainly what it does not do, and asks nothing of you — no account, no install, no server. You copy the file and it works.

That severe shape is not a limitation we tolerate; it is the point. A gift is honest by construction: there is nowhere for a hidden dependency, a phone-home, or an unstated assumption to live. This guide is how you build one our way — through a path that makes every one of those honesty properties a checked fact rather than a promise.

This is the builder's guide. If you want to use the gifts to compose something, the Gifts Users Guide teaches that. This one teaches how to make a new gift and bring it into the cabinet.

The covenant — the four things that make a gift a gift

Before any procedure, hold the covenant. These four properties define a gift; break any one and what you have is a tool, not a gift. Each is a loud stop, not a warning to absorb — the path refuses at the covenant, at the gate, deliberately.

• MIT licensed. Anything else is a loud stop. A gift is given away.
• Zero dependencies. No npm, no imports, no runtime you don't ship. A single file that stands alone.
• Two homes, byte-identical. A gift lives in two places: its design home (the private tree where it is authored) and the served tree (<served>/gifts/<slug>/, the public copy). The two must be byte-for-byte the same — a decidable cmp, not a hope.
• A printed edge. One sentence, shipped in the file, stating what the gift does not do — so a caller cannot misuse it. sha256's edge: a hash, not encryption, not a password KDF — it proves two inputs match, it keeps no secret.

The path — five moves, in order

You build a gift by walking The Gift-Works Procedure: five moves forward, plus a strip that precedes them and a landing that closes them. The moves are ordered. A missing or stale predecessor is a loud stop, never a fast path. Each move ends in a decidable byte-oracle — a cmp, a byte-equal trace, a hash — so a deviation is caught at its step, not discovered at ship.

1. Step 0 — The strip. A gift usually already exists as code inside a larger tool. You strip it out: extract the pure function, cut everything that tied it to its old home, and record what tool it came from and what you cut. That provenance is the gift's most valuable decision. Read the stripped code first — the one-line description is a lead, not a spec (this line mis-scoped a candidate three times by trusting the gloss).
2. Step 1 — The Blueprint. Author the gift's canonical Blueprint against the Gift Blueprint Profile. The Blueprint is the product; the code is the artifact. It states what the gift is: its identity, its in-type → out-type signature and the fidelity rule that binds them (this is the single most load-bearing line — sha256's is String → 64-char lowercase hex, hashing UTF-8 bytes, never char codes), its two surfaces (CLI and browser attach), and the covenant's four fields as declared facts. Register it, or it does not exist.
3. Step 2 — The Plumb. Bless what perfect looks like: a reference build, a golden input/output corpus, and the invariant contract. The golden corpus draws its known-bad half from real defects — the bug that actually bit once becomes the tripwire — never from author-invented failures. The canonicalizer's self-test is the gift's own determinism check: run it under many seeds, assert the output is byte-identical every time. For a gift, that is the proof it is a pure function.
4. Step 3 — The Agent File. Render the gift's AGENTS.md from the Blueprint plus the gift config. It homes in the gift's own design tree, alongside the gift file — a gift binds no constellation, so its design tree is its project. Every place the gift bends from the default maps to a declared config point, or it is a loud stop.
5. Step 4 — Conformance. Run the out-of-band checker: replay the Plumb's blessed scenario, apply the one canonicalizer to both sides, and byte-compare the traces. Emit a signed, version-pinned conformance record. Non-conformance is no ship, loudly. This is the load-bearing addition — shipped means the trace conforms to the Plumb, not merely that the tests pass.
6. Step 5 — Acceptance & landing. Run the Self-Review Pull against live bytes, examine the finished gift for one genuine improvement to promote back into the Blueprint (so the next gift renders from a warmer path), then land it through the close. Every ship gate the line already runs stays; conformance is the new one.

The loopback — why every gift makes the next one easier

The fifth move carries the part that makes this a system rather than a conveyor belt. When a gift is finished, you look back at it and ask: did building this teach me something the Blueprint should know? A sharper invariant, a better edge sentence, a stronger canonicalizer, a reusable shape. If it is genuine, you promote it — an atomic write back into the Blueprint and Plumb that render the next gift.

So the path is not run-once. It is run → formalize → run → sharpen. The first gift (sha256) was walked cold, then this procedure was written from the doing. Every gift since renders from a warmer Blueprint than the last. That is the loop worth building for.

A worked example — sha256, end to end

The cleanest first pass through the whole cycle was sha256: browser-synchronous SHA-256, hex out. Small, pure, decidable from bytes, with obvious golden vectors and a canonical form that is the output (the hash is its own canonical form). Here is the trail, so you can see the five moves as real acts, not abstractions:

1. Strip: extracted from an internal shell tool to the served tree — already shipped, but with no canonical tier (no Blueprint, absent from the registry).
2. Blueprint: authored against the gift profile; a design→canonical flip for an already-existing artifact, with the strip recorded as its first provenance entry.
3. Plumb: golden vectors from Node's own crypto library (the out-of-band oracle) plus a multibyte known-bad vector — the tripwire for the char-code bug that bites naive SHA-256 implementations. The determinism lint is the canonicalizer self-test.
4. Conformance: the out-of-band checker plus a signed, version-pinned record (trace vs Plumb, canonicalizer version, seed set).
5. Acceptance: rendered the Agent File in the design home, ran the Pull in place (every claim re-verified against live bytes), found one real over-generalization and routed it to the operator, then landed — with the two homes held byte-identical by the cmp gate.

The loud stops — where the path refuses

A gift's path refuses, loudly, at any of these. None is a warning to route around; each is a stop to surface — because a gift that bends here is not a gift.

• a non-MIT license, or any dependency (the covenant);
• a stale or missing Blueprint or Plumb at the gate;
• a byte difference between the two homes;
• a missing printed edge, or a Blueprint edge that disagrees with the shipped edge;
• non-conformance to the Plumb;
• a multi-file format — a gift is single-file by definition.

Building in a wave — when gifts arrive together

The path above builds one gift. But gifts rarely arrive one at a time — they come in waves: a batch commissioned together, built in parallel, landing over hours or days. A wave changes nothing about the covenant or the five moves — each gift still walks the whole path and passes every gate alone. What a wave adds is three relationships between gifts, and each is a loud stop of its own.

Declare the port-verb — how a gift joins a pipeline

Every gift declares one port-verb in its Blueprint — source, transform, filter, fold, or sink — the single word that says how it composes. This is not decoration: it is what lets a pipeline be proven valid before it runs. Build the verb in from the Blueprint, not bolted on after. A gift with no declared verb is a gift no one can safely snap onto another — it fails the composition contract even when it passes its own tests. (How a user reads these verbs to compose a pipeline is the Gifts Users Guide's job; your job as builder is to declare the verb honestly, so the user's type-check tells the truth.)

The pair-braid — when two gifts are one unit

Sometimes two gifts are commissioned as a pair that only makes sense together — one splits, its partner rejoins; one opens, its partner closes. When that happens, neither ships until the pair round-trips. The worked instance is fanout (the ⊗-open: split one input into a declared, closed set of named branches) paired with junction (the ⊗-close: fold those branches back under a declared merge policy). Fanout is not done when fanout's own tests pass — it is done when a fanout → junction braid round-trips byte-identically under a declared merge policy. The braid is the acceptance test; the two Blueprints share it. Build a pair by building the braid, not two gifts that happen to be adjacent.

Binding dependencies — when one gift needs another

A gift may be bound to another by construction: it cannot ship without its dependency present and honest. When that binding exists, it is a covenant field, not a nicety — the path refuses if the dependency is absent. In the current wave, seance (channel a deleted prompt from git history) is Scrub-bound: it must route its recovered text through scrub before it surfaces, or it does not ship — recovering a secret someone deleted on purpose is the exact harm the binding prevents. Declare the binding in the Blueprint, gate on it at conformance, and treat a missing dependency as a loud stop.

What "landing" means while you wait

In a wave, the cabinet below will show some siblings as landing — named, commissioned, not yet in served bytes. That is not an error; it is the honest state of a gift still in flight. Three from the current prompt-gift wave are landing as this is written: scrub (strip declared-shape secrets from a prompt before paste — shapes, not semantics), contract (assert a model's JSONL output matches a declared record schema at runtime — reject the first bad record, name the field), and seance (above, Scrub-bound). When each lands in served bytes, the cabinet folds it from landing to shipped on its own — the appendix is derived from The Tally, not hand-edited. A builder joining the wave reads the cabinet to see which siblings are still open, and builds theirs to the same path.