lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore(openwolf): update session memory, buglog, and anatomy tracking

Browse source 
Records bug-1461/1462 fixes, admin-config-tool completion, and
config-upgrade-snapshot spec work across anatomy.md, buglog.json,
cerebrum.md, memory.md, and the session/token-ledger state files.
This commit is contained in:
Rongsong Shen 2026-07-23 04:29:12 +00:00
parent 8ee98beed7
commit 60c25c39c4
6 changed files with 23648 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.wolf/cerebrum.md
View file

@ -509,3 +509,9 @@ tasks.md showed 18/18 (12 leaf + 6 group-header) checked since 2026-06-16, and r
Fixed two `xce-audit-invariants controller` thread-role violations (`ha_demotion_convergence_fn` ha_convergence.c, `ha_catchup_continuation_fn` config_repl.c — both ran blocking work directly on the delaymgr thread) by adding a 4th/5th instance of the established slow-lane pattern (`slowlane_submit`/`*_lane_fn`, mirroring `ha_snapshot_send_dispatch`/`ha_config_push_offloadable`/`ha_connect_to_peer` in ha.c) — NOT the VTASK_LIVE_BLOCK vtask-pool approach a prior session tried and reverted (bug-1429) after it deadlocked `controller_unit_test`. Confirmed via `git log`/memory why that attempt failed: `c->ha.pool` was never initialized in the lightweight unit-test fixtures it ran against, so `vtask_enq_classified(..., VTASK_LIVE_BLOCK)` blocked forever waiting for a worker that didn't exist. `slowlane_submit` is architecturally immune to THAT failure mode (it is unconditionally non-blocking — with zero live workers it just returns `-EAGAIN`/`0` and leaves the work queued-but-never-run, never blocks the caller). BUT defaulting the new offload flags to ON (`g_drive_async_demotion_offload`/`g_drive_async_catchup_offload = 1`) reproduced a REAL hang anyway, via a DIFFERENT mechanism: the production callback being offloaded (`raft_cb_become_follower` for demotion, `ha_walack_on_ack`/`ha_catchup_continuation_fn` for catch-up) is exercised by a VERY BROAD set of PRE-EXISTING `controller_unit_test` fixtures across many files (confirmed hit: `test_convergence_verification.c`'s ACK-driven catch-up suite) that never call `slowlane_init` — so the offloaded work is silently queued on an uninitialized lane and NEVER RUNS, and any downstream code (in THOSE pre-existing tests, not the new ones) that waits — even boundedly — for the now-never-happening completion stalls/times out. Reproduced with a direct standalone binary run (`timeout -s QUIT 90 ./controller_unit_test`, bypassing meson) BOTH before (hang, SIGQUIT after 90s) and after (clean, "976 Tests 0 Failures 0 Ignored") the flag-default flip to OFF. **General rule**: when adding a NEW slow-lane offload flag for an existing, widely-exercised callback, default it OFF and add your own dedicated tests that explicitly flip it ON against a fixture you control (with `slowlane_init` called) — do NOT default a new offload flag ON just because the lane mechanism itself is provably non-blocking; the blast radius of "which pre-existing fixtures reach this code path without lane infra" is the real risk, and it can only be ruled out by a full test-suite compatibility audit (exactly how the ORIGINAL three raft-drive-async offloads were rolled out: shipped OFF, flipped ON only in a later dedicated task-3.4-style pass). Always verify a "fixed hang" claim by running the STANDALONE `controller_unit_test` binary directly with an external `timeout -s QUIT`, not just `meson test` (whose `Ok:N/Fail:0` aggregate can hide a TIMEOUT line entirely if you only grep for `Fail:`) — grep for `Timeout` explicitly too.
## Key Learning (2026-07-18) — `test_convergence_verification.c` is the direct, pre-existing test surface for `ha_walack_on_ack`/`ha_catchup_continuation_fn` (the ACK-driven catch-up decision, ha-convergence-recovery task 4.x); it drives them via `ha_walack_continuation_for_test` against a real-but-un-started `delaymgr` and has NO `slowlane_init` — any future change that makes catch-up continuation offload-capable must either default OFF or update this file's fixture.
## Do-Not-Repeat (2026-07-21, admin-config-tool task 1.3, bug-1458) — adding `python3Packages.{pycapnp,pyyaml,jsonschema,click,pytest,ruff}` to a nix `nativeBuildInputs` list does NOT put a `pip` executable on `$PATH`; none of those packages pull one in transitively. You must add `python3Packages.pip` explicitly if any build step needs to run `pip install`. brief.md's own suggested package list for xceadmin omitted it — verified by actually running the resulting `nix develop` shell end-to-end, not by reading the package list.
## Do-Not-Repeat (2026-07-21, admin-config-tool task 1.3, bug-1459) — a nix-provided `python3`'s site-packages lives under the read-only `/nix/store`, so `pip install`/`pip install -e .` against it directly fails with "externally-managed-environment" (PEP 668), even from inside `nix develop`. Fix pattern: `python3 -m venv --system-site-packages "$VENV_DIR"` (inherits the nix-provided heavy binary deps like `pycapnp` for free, so pip never re-downloads/rebuilds them) then run `pip`/`python` via `"$VENV_DIR/bin/..."`, not bare. This is the general pattern for any future nix + `pip install` component in this repo, not xceadmin-specific.
## Do-Not-Repeat (2026-07-21, admin-config-tool task 1.3, bug-1460) — a Python package's non-`.py` data files (here: `xcecommon/schema_files/*.capnp` and `schema_files/json/*.schema.json`) are silently DROPPED from a wheel built by `pip install .` (non-editable) unless declared via `[tool.setuptools.package-data]` in `pyproject.toml`. An editable install (`pip install -e .`) never catches this — it resolves straight into the checked-out source tree, bypassing wheel packaging entirely. Any bundled-non-code-asset pattern in this repo's Python components needs an explicit `package-data` entry, and the ONLY way to verify it works is to actually run the non-editable/`release` install profile and inspect `site-packages`, not just the editable one.