From 4af8fb31e29a73b2d635761dff7d3750e152a8c3 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Fri, 10 Jul 2026 11:30:00 -0700 Subject: [PATCH] docs: pin the write-path invariant in the plugin contract (the onChange change-feed guarantee) --- docs/PLUGINS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 0a553d46..d9a4d3e7 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -149,6 +149,17 @@ context.registerProvider('embedBatch', async (texts: string[]) => { ### Index Providers +> **Write-path invariant (the change-feed contract).** Every canonical +> mutation flows through Brainy's generation-store commit points — index +> providers are invoked *inside* that commit and never originate canonical +> writes of their own. The `brain.onChange` change feed is emitted from those +> commit points and relies on this: **a plugin must never introduce a write +> path that bypasses the generation-store commit.** If a future provider ever +> needs a direct native ingest path, it must either route through the commit +> or emit equivalent change events — otherwise every `onChange` consumer +> (live UIs, cache invalidation, realtime sync) silently develops a blind +> spot. + #### `vector` **Type:** `(config: object, distanceFunction: Function, options: object) => VectorIndexProvider-compatible`