architecture: extract a shared Flatbread write path when write capability broadens

[tonyketcham]

This was generated by AI during triage.

Why this is tracked

Flatbread started as a read-only way to query content stored in files. That remains important for blogs and static sites.

The Effort Graph already has a write path: an agent issues a semantic command, the writer saves the change safely, Flatbread refreshes its graph, and the agent can read the result. That path is intentionally specific to Effort Graph files and lives outside core. It is the first working example, not a general Flatbread write system for every collection or source.

See ADR-0009: When to extract a shared write path into Flatbread.

Future direction

When Flatbread needs more writable systems, extract the common save-and-refresh behavior into Flatbread itself:

files or another source
        ↕
shared save + refresh behavior in Flatbread
        ↕
GraphQL, CLI, agents, or a CMS

A source that supports writing should explain how to read a record and how to save it again. A transformer that participates in writing must do the same for its document format. A single requested change may update several records, so it must either finish completely or leave the data unchanged. Flatbread should refresh the graph only after the saved data has been checked. Sources that only support reading should continue working as they do today.

Revisit this before adding another writable system when

• we need to write to a second kind of source, such as a database or remote service;
• a CMS needs drafts, revisions, conflict handling, media, or publishing permissions;
• another feature would copy the Effort Graph's file-writing, recovery, or live-refresh code; or
• we want ordinary Flatbread collections to have GraphQL mutations.

Until then

• Keep Effort Graph semantic commands as the supported write API.
• Keep GraphQL read-only for ordinary collections; any future Effort Graph GraphQL interface must call the existing writer.
• Route new Effort Graph writes through the existing journal and committed-generation bridge.
• Finish and use the agent read/write flow before designing the general shared write path.

Definition of done

• Describe the shared write path and how Effort Graph becomes an adapter over it.
• Explain source write support, transformer read/save behavior, multi-record save-or-none rules, and graph refresh after checked saves.
• Validate the design with a second writable source or use case.
• Keep the existing static/read-only setup working without enabling writes.