One Small Record

"Everything a transformation is — its name, its instruction, its trigger, its appetite for context — fits in one small record."

The Whole Transformation in One Record

A FlintMacro is a small value type that holds everything needed to run one transformation and nothing else. A stable id. A human name. The prompt template that defines what it does, with an {input} slot for the selection. Whether it's enabled. An optional chord. Its vault-context mode. When it was created. That's the entire object. There's no model, no state, no history hiding in it — a macro is a description of an intent, not an engine.

Why the UUID Is Stable

The id is a UUID assigned once, at creation, and never changed — not when the user renames the macro, not when they rebind its chord, not when they edit the template. That stability is what lets everything else refer to the macro safely: the hotkey center keys its registration by this id, the palette lists by it, and a rebind is 'unregister id, register id with new keys' rather than 'destroy and recreate.' A name can change and a chord can change, but the identity underneath stays fixed.

id           : fixed forever (the true identity)
name         : editable      (what the human calls it)
template     : editable      (what it actually does)
hotkey       : editable      (how it's triggered)
vaultMode    : editable      (how much context it needs)

Everything mutable hangs off one immutable id.

A Value Type, Codable

Because a macro is just data, it's a Codable value type, and persistence is trivial: encode the list to a local JSON file Flint owns, decode it on launch. No database, no migration engine, no sync — a small array of small records in a file. The simplicity is deliberate and it's a feature: a macro store you can open, read, and understand as plain JSON is a macro store you can trust and debug.

Give every editable thing a stable identity that isn't the thing you edit. If you identify a record by its name or its shortcut, then renaming or rebinding it breaks every reference. A separate, immutable id decouples 'which record this is' from 'what this record currently says,' so all the mutable fields can change freely while everything that points at the record keeps working. The id is the anchor; everything else is allowed to move.

Plain JSON persistence is a debugging feature, not a limitation. Because the macro store is a readable JSON file, you can inspect exactly what Flint will run without launching anything, hand-edit a macro in a pinch, and diff two versions to see what changed. Reaching for a database here would trade that transparency for machinery the data doesn't need. Small, readable, on-disk beats opaque-but-fancy for a list this size.

Code

FlintMacro — the whole domain object·swift

struct FlintMacro: Codable, Identifiable, Equatable {
    let id: UUID                    // assigned once, never changes
    var name: String
    var promptTemplate: String      // contains the {input} placeholder
    var enabled: Bool
    var hotkey: HotkeyBinding?      // optional; the palette reaches it anyway
    var vaultContextMode: VaultContextMode
    let createdAt: Date

    func render(input: String) -> String {
        promptTemplate.replacingOccurrences(of: "{input}", with: input)
    }
}

enum VaultContextMode: String, Codable {
    case useVault      // full personal context: slower, richer
    case bypassVault   // no context: faster, private, shallow
}

Exercise

A user renames their 'Correct' macro to 'Fix Typos' and changes its chord from Cmd+Shift+C to Cmd+Shift+F. Walk through which fields change and which stay fixed, and explain why the hotkey center and any usage history keep working across both edits. What would break if the macro were identified by its name instead of a UUID?

Hint

name and hotkey change; id, template, vaultMode, and createdAt stay. The hotkey center rebinds by the unchanged id (unregister id, register id with new keys), and any history keyed by id still points at the same macro. If the macro were identified by name, the rename would sever every reference — history would orphan and the rebind would look like a different macro entirely.

The Whole Transformation in One Record

Why the UUID Is Stable

A Value Type, Codable

Code

External links

Exercise

Progress

Comments 0