driver/yaml's sink spends 88% of a save on an fsync no caller can decline

[ajatprabha]

A Dump through driver/yaml issues one fsync and it is 2.2ms of a 2.38ms save on ext4 (#186), or 88% of the operation.
Nothing lets a caller decline it.

For a config file a process is about to re-read, or a file being written in a test, or any of the cases where the atomic rename is the point and surviving a kernel panic is not, that is the whole cost of the operation spent on a guarantee the caller did not ask for.
koanf, viper's non-atomic write and a plain os.WriteFile all sit between 210µs and 380µs; ferry with the same fsync removed sits at 390µs and ties koanf.

The decision this needs

No ADR owns durability policy for a driver, so this is an unmade decision rather than a correction to an existing one - do not amend an ADR into saying something it never decided, and do not open a new one without asking the owner first.
#155 is the precedent for the shape: a driver-level Option on the constructor, decided in the ticket.

The question is only which way the default points:

• unsynced default, Durable() opts in - matches every library ferry is measured against, makes the common case fast, and means a caller who wants the journal commit says so. The atomic rename stays unconditional either way, because that is what protects the operator's file from a half-written document and it costs 53µs.
• synced default, Unsynced() opts out - preserves today's behaviour for anyone already relying on it, which as of this ticket is nobody outside the repo.

Recommendation is the first: atomicity is the promise doc.go makes and it is kept in both, durability is the expensive one, and a library that silently spends 2.2ms per save on it has made a choice for the caller.
The owner decides; the ticket does not.

Scope

• NewSink(path string, opts ...Option), variadic and backward compatible.
• Whichever default is chosen, doc.go's "Saving is atomic" section says what is and is not guaranteed, and the option's own godoc says what the caller is buying or declining. Neither prints a measurement (AGENTS.md).
• Blocked by driver/yaml fsyncs the staged file and never the directory the rename lands in, so an atomic save is not a durable one #187: settle what a durable save actually is before making it optional, so the option is not switching between two things that are both wrong.

Parent: #186
Blocked by: #187

[ajatprabha]

Owner ruling, 2026-08-04: unsynced default, Durable() opts in. That is what #195 implements, so no change follows from this - it is recorded because the ticket said the decision was the owner's and not the ticket's, and the PR should not read as though an agent settled it.

The two rejected alternatives and why:

• Durable default with Unsynced() opting out. Preserves every existing caller's guarantee and changes nothing silently, but makes the default the slowest thing ferry does: 4.55ms against main's 2.45ms today, because driver/yaml fsyncs the staged file and never the directory the rename lands in, so an atomic save is not a durable one #187 adds the directory flush that was missing. Every save pays a journal commit unless the caller knows to decline one.
• No option at all, always durable. Smallest API and driver/yaml fsyncs the staged file and never the directory the rename lands in, so an atomic save is not a durable one #187 alone needs no decision, but every caller pays ~4.5ms with no way out - tests, scratch files, and any config a process is about to re-read itself - and ferry would be the only library in the comparison with no way to decline.

The consequence being accepted, stated plainly so it is not discovered later: today a save fsyncs, and after this it does not. There is no compile error and no runtime signal. A caller relying on the flush loses it and finds out on a power cut. That blast radius is zero today because core is not tagged and no external caller exists, and it is non-zero the day after it is - which is the argument for landing it now rather than later.

Atomicity is not part of this trade. The rename is unconditional in both modes, so nothing ever reads a half-written config and a save that fails still leaves the file byte for byte as it was.