omnigraph/docs/user
Ragnor Comerford 08cfd9f843
fix(engine): run __run__ sweep at Omnigraph::open, not only on publish
Review (PR #132) caught a regression: removing __run__ from
`is_internal_system_branch` exposed legacy `__run__*` branches to the
schema-apply blocking-branch checks (schema_apply.rs:104 and :778) and to
`branch_list()`, but the v2→v3 sweep ran only inside the publisher's
`load_publish_state`. On a pre-v0.4.0 graph whose first write is a schema
apply, the blocking-branch check fires before any publish, so apply failed
with "found non-main branches: __run__…". The same lazy timing also created a
reverse hazard: a user-created `__run__*` branch on a still-v2 graph could be
deleted by the first publish's sweep.

Fix: run the internal-schema migration in `Omnigraph::open(ReadWrite)` (new
`manifest::migrate_on_open`), before the coordinator reads branch state. The
sweep now lands before any branch-observing code, and a graph is stamped v3 at
open — so the one-time sweep can never catch a legitimately-created branch.
Both checks and `branch_list` see the swept graph; correct by construction for
every write path.

Accepted residual: a read-only open of an unmigrated legacy graph still lists
`__run__*` (read-only opens must not write, so they can't sweep). Documented.

Regression test `legacy_run_branch_is_swept_on_open_and_does_not_block_schema_apply`
confirmed RED before the fix (panicked on the branch_list leak assertion) and
GREEN after. Also updates the stale schema_apply.rs comment, the writes.md
"Migration code" section, and adds the v3 row to storage.md's migration table.
2026-05-31 15:45:32 +02:00
..
audit.md refactor(engine): remove the legacy __run__ branch guard (MR-770) 2026-05-31 15:45:32 +02:00
branches-commits.md refactor(engine): remove the legacy __run__ branch guard (MR-770) 2026-05-31 15:45:32 +02:00
changes.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
cli-reference.md feat: inline query strings in CLI and HTTP server (#110) 2026-05-29 13:41:54 +02:00
cli.md feat: inline query strings in CLI and HTTP server (#110) 2026-05-29 13:41:54 +02:00
constants.md refactor(engine): remove the legacy __run__ branch guard (MR-770) 2026-05-31 15:45:32 +02:00
deployment.md feat(server): compose OMNIGRAPH_TARGET_URI with OMNIGRAPH_CONFIG in entrypoint (#129) 2026-05-30 20:17:55 +01:00
embeddings.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00
errors.md docs: rename runs.md/runs.rs → writes and repoint all references (#131) 2026-05-30 23:20:56 +02:00
index.md Rename repo terminology to graph (#118) 2026-05-24 16:46:00 +01:00
indexes.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
install.md Add Windows release binaries (#127) 2026-05-30 14:23:40 +02:00
maintenance.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
policy.md (feat): multi-graph server mode (#119) 2026-05-28 16:19:31 +02:00
query-language.md docs: rename runs.md/runs.rs → writes and repoint all references (#131) 2026-05-30 23:20:56 +02:00
schema-language.md schema: HTTP allow_data_loss exposure + e2e drop coverage (MR-694 follow-up) (#107) 2026-05-19 01:56:46 +03:00
schema-lint.md docs: split user and developer docs (#93) 2026-05-15 03:45:22 +03:00
server.md feat: inline query strings in CLI and HTTP server (#110) 2026-05-29 13:41:54 +02:00
storage.md fix(engine): run __run__ sweep at Omnigraph::open, not only on publish 2026-05-31 15:45:32 +02:00
transactions.md docs: rename runs.md/runs.rs → writes and repoint all references (#131) 2026-05-30 23:20:56 +02:00