Send a Prompt, Not a Reference

"Flint renders the whole prompt itself and sends the finished text. It never asks the brain to look something up."

Render Locally, Send Finished

The contract is named 'apply-free' because Flint applies a free-form prompt: it does the template rendering on its own side, drops the captured selection into the {input} slot, and produces a finished prompt string. Only then does it call across the boundary. The brain receives complete text to transform, not a template to fill in and not a name to resolve. Rendering is Flint's job; thinking is the brain's.

What Crosses the Wire

The request carries three things: the rendered prompt, the vault-context choice, and — for the local model tiers — which tier and model to use. That's the entire contract. The prompt is the content; the vault choice and tier are the execution parameters that tell the brain how to run it. There is no session, no history, no reference to anything stored elsewhere. Each call is self-contained: everything the brain needs to answer is in that one request.

Vault bypass is explicit on the wire — never a hidden default. Whether a macro runs with full personal vault context or bypasses it entirely is a real decision with real consequences (latency, and what the model knows about you). So it travels as an explicit field in every request, set per macro. An empty soul or a missing field must never quietly become a performance shortcut; the choice is stated out loud, every time, so no request silently sends more or less context than intended.

Never a Macro ID

The most important field in the request is the one that isn't there: a macro id. Flint never says 'run macro number 7 that you have stored.' It sends the actual prompt. This is deliberate — the moment Flint referenced a brain-side macro by id, the two systems would be coupled through that id, and the independence the next lesson is about would be gone. Send data, not a pointer to someone else's data.

Send the content, not a reference to content the other side holds. A self-contained request that carries everything it needs is decoupled from the callee's internal state; a request that names an id the callee must look up is coupled to whatever that id means over there. When you can afford to send the whole thing, do — it trades a few bytes for the freedom to change both sides independently.

Code

The apply-free request — a finished prompt, no macro id·swift

struct ApplyFreeRequest: Encodable {
    let prompt: String        // fully rendered; {input} already inlined
    let vaultBypass: Bool     // EXPLICIT on the wire, never a hidden default
    let ollamaTier: String?   // local / server / cloud
    let model: String?
    // Deliberately NO macroID field: Flint sends a prompt, not a pointer
    // to something the brain stored. That absence keeps the systems apart.
}

func applyFree(_ req: ApplyFreeRequest) async throws -> String {
    var request = URLRequest(url: brainURL)   // .../utility-macros/apply-free
    request.httpMethod = "POST"
    request.httpBody = try JSONEncoder().encode(req)
    // ... send, decode the transformed string from the response ...
}

What the body looks like on the wire·json

{
  "prompt": "Fix the spelling and grammar. Return only the corrected text.\n\nteh qiuck borwn fox",
  "vaultBypass": true,
  "ollamaTier": "local",
  "model": null
}

Exercise

Flint could have been designed so it stores a macro on the brain and just sends 'run macro 7' with the selection. List the couplings that design would create, and contrast them with what the apply-free (send-the-whole-prompt) design costs and buys instead. Separately: why does vault bypass have to be an explicit field rather than inferred from whether a soul is set?

Hint

The 'run macro 7' design couples the two catalogs through the shared id: editing the brain's macro silently changes Flint's behavior, and neither list can move without the other. Apply-free costs a few extra bytes per call and buys full independence. Vault bypass must be explicit because inferring it from an empty soul turns a knowledge/latency decision into an invisible side effect — the request would send different context than the author realized, which is exactly the hidden-default trap the contract forbids.

Send a Prompt, Not a Reference

Render Locally, Send Finished

What Crosses the Wire

Never a Macro ID

Code

External links

Exercise

Progress

Comments 0