mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-28 14:59:47 +00:00
cd8efee0ea
* feat(sync): migration v98 last_refreshed_at + deleteLockRowIfStale helper Schema foundation for v0.41.15.0's `gbrain sync --break-lock --max-age <s>` flag. Adds `gbrain_cycle_locks.last_refreshed_at TIMESTAMPTZ` as the heartbeat signal that distinguishes wedged-but-alive lock holders from healthy long-running syncs that are actively refreshing. Why last_refreshed_at not acquired_at: `withRefreshingLock` already bumps `ttl_expires_at` every ~5 min while work runs, but leaves `acquired_at` at the original timestamp. A 35-min media-corpus sync that's healthy has `acquired_at` 35 min ago but `last_refreshed_at` 30 seconds ago. Using acquired_at for --max-age would steal healthy locks; last_refreshed_at correctly identifies only holders whose JS interval has stopped firing. D-V4-1 rollout safety: migration v98 backfills `last_refreshed_at = NOW()` (NOT `= acquired_at`) so pre-upgrade holders running the old binary get a 30-min protection window. After that window all pre-upgrade syncs are either complete (lock released) OR genuinely wedged (--max-age does the right thing). Documented as a known caveat in CHANGELOG. D-V4-mech-4 SQL cast: deleteLockRowIfStale uses `$N * INTERVAL '1 second'` not `$N::interval` (Postgres does not cast integer to interval the latter way). Atomic DELETE keyed on (id, holder_pid, last_refreshed_at < NOW() - $N * INTERVAL '1 second') RETURNING id, last_refreshed_at — no TOCTOU between inspect + delete. D-V4-mech-3 schema-snapshot parity: column added to all 3 snapshots so fresh init paths (pglite-schema.ts, schema.sql) initialize correctly without depending on the migration runner. schema-embedded.ts regenerated via `bun run build:schema`. Pinned by 13 PGLite cases in test/sync-break-lock-all.test.ts: tryAcquireDbLock writes on INSERT, withRefreshingLock refresh bumps both columns, inspectLock surfaces the new field, deleteLockRowIfStale refuses fresh / breaks stale / safe on holder_pid mismatch / refuses NULL (pre-v98). R1 + R6 regression invariants from the v4 plan. Closes #1472 (RFC from @garrytan-agents) — schema foundation only; performSync abort threading + CLI flags + consumer threading land in follow-up commits in this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(sync): --timeout + --max-age + partial status + per-source AbortController The CLI surface for v0.41.15.0. Wires `gbrain sync --timeout <s>` (graceful self-termination) and `gbrain sync --break-lock --all --max-age <s>` (cron-self-heal) end-to-end through `performSync`, `runOne`, `runBreakLock`, and all `SyncResult.status` consumers. Surface 1: `gbrain sync --timeout <s>` - New `SyncOpts.signal?: AbortSignal` threads through `performSync` → `withRefreshingLock` work callback → `performSyncInner`. - D-V3-1 honest scope: abort checks fire ONLY in pre-bookmark phases (pull, delete, rename, import). Extract + embed run to completion if reached. The `last_commit` bookmark write at sync.ts:1261 is the invariant boundary — partial CANNOT advance the bookmark because the abort checkpoints sit strictly before that write. - D-V3-2 per-iteration: abort check at top of every loop iteration (delete, rename, serial import, each parallel worker's while loop) matches the per-file granularity the existing loops already have. - D-V3-3 per-source AbortController: `--timeout --all` creates ONE controller inside runOne per source so each gets its own budget; NOT a shared global controller (which would starve later sources). try/finally + timer.unref() guarantees cleanup on throw. - D-V4-mech-7 pull error.cause: pullRepo wraps execFileSync errors in GitOperationError. The catch inspects e.cause.code === 'ETIMEDOUT' and e.cause.signal === 'SIGTERM' (NOT the top-level error) to distinguish timeout (partial reason='pull_timeout') from ordinary pull failure (existing warn-and-continue, R2 invariant preserved). Surface 2: `gbrain sync --break-lock [--all] [--max-age <s>]` - Drops the --all refusal at sync.ts:1610. When combined with --all, runBreakLock iterates every active source and prints per-source verdict. - --max-age routes through the new deleteLockRowIfStale helper from db-lock.ts (atomic age-gated DELETE; no TOCTOU). Healthy refreshing holders survive by construction; only wedged-but-alive holders trip. D-V3-5 partial-status consumer threading (conservative posture matching blocked_by_failures): - printSyncResult: new `case 'partial':` arm reports filesImported + reason; tells operator to re-run to continue. - manageGitignore (both single-source and parallel runOne sites, plus watch mode): excludes partial from the gate. A partial sync's db_only path set isn't fully reconciled. - Auto-embed-backfill enqueue inside runOne: excludes partial. The next clean sync will re-walk and re-decide. CLI flag parsing (T16): - parseDurationSeconds in sync-concurrency.ts: accepts 60s/10m/1h/bare int; rejects 0/negatives/decimals/garbage. Names the failing flag in the error message. - --timeout requires --source OR --all (validation rejects bare `gbrain sync --timeout`). - --max-age requires --break-lock; mutually exclusive with --force-break-lock. Coverage: - 15 unit cases (test/sync-timeout.test.ts) pin parseDurationSeconds + SyncResult union additivity. - 2 E2E cases (test/e2e/sync-parallel.test.ts) pin the abort-mid-import contract against real Postgres: status='partial', last_commit unchanged, filesImported bounded. Closes #1472 (RFC from @garrytan-agents) — CLI surface; schema foundation landed in the previous commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(heavy): sync_timeout_rescue.sh reproducer for the cron-cascade 10K-page seed × 4 sources × deliberately tight --timeout × 3 sequential cron emulations. Asserts every source reaches `last_commit === HEAD` within 3 waves. Proves the v0.41.15.0 fix breaks the cascade the PR #1472 RFC documented. Workload (tests/heavy/_sync_timeout_rescue_workload.ts) is PGLite-only because the PGLite engine forces serial sync internally (parallelEligible excludes it). The parallel-fan-out + per-source AbortController case lives in test/e2e/sync-parallel.test.ts against real Postgres. This heavy test pins the contract that matters for cron: aborts → partial returns → next wave content_hash-short-circuits + makes new progress. Smoke-tested locally at PAGES=50 WAVES=2 TIMEOUT_SECONDS=2: every source converges within 2 waves. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(v0.41.15.0): CHANGELOG + README + TODOS + version bump Bumps VERSION + package.json to 0.41.15.0 (next slot after master's v0.41.14.0). CHANGELOG entry leads ELI10 per gstack voice rules and documents the 3 intentional honest gaps: 1. --timeout covers pull + delete + rename + import only; extract + embed run to completion (D-V3-1 honest scope). 2. First 30 min after migration v98, --max-age cannot identify wedged pre-upgrade holders (D-V4-1 rollout trade-off). 3. Full-sync triggers (first sync, --full, chunker-version rewalk) don't respect --timeout yet (deferred to v0.42+). README troubleshooting section: paste-ready cron pattern with shell timeout(1) for OS-level process isolation + gbrain's --timeout for graceful self-termination half-a-minute earlier. TODOS.md: v0.42+ entries for subprocess fan-out (revisit if shell timeout(1) proves insufficient), full-sync --timeout coverage via AbortSignal in runImport, and runFactsBackstop microtask-queue process-alive caveat. llms-full.txt regenerated via `bun run build:llms`. Closes #1472 (RFC from @garrytan-agents). Credit to @garrytan-agents in the CHANGELOG for surfacing the production cron-failure data that motivated the work. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(test-isolation): rewrite JSDoc to not match mock.module() lint regex scripts/check-test-isolation.sh greps for the literal string `mock.module(` to flag top-level module mocks (R2 rule — top-level mocks leak across files in the shard process). The regex doesn't know about comments, so my two new test files tripped the lint with JSDoc lines literally describing the rule: test/sync-timeout.test.ts:11 "* `mock.module()` (R2). Engine ..." test/sync-break-lock-all.test.ts:15 "* mock.module(), no process.env ..." Both files had ZERO actual mock.module() calls — only the comment text matched. Rewrote both JSDocs to refer to "top-level module mocks" instead of the literal token. Same meaning; doesn't trip the regex. `bun run check:test-isolation` now passes (714 non-serial unit files scanned). `bun run verify` clean (22/22 checks pass). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
87 lines
3.4 KiB
Bash
Executable File
87 lines
3.4 KiB
Bash
Executable File
#!/usr/bin/env bash
|
||
# tests/heavy/sync_timeout_rescue.sh
|
||
#
|
||
# v0.41.13.0 (T9) — reproduce the PR #1472 RFC's "8 of 12 cron timeouts at
|
||
# 1803s" scenario at smaller scale and assert that the v4 fix breaks the
|
||
# cascade.
|
||
#
|
||
# Production failure mode (RFC):
|
||
# - 4 federated sources × 370K pages
|
||
# - hourly cron with 30-min wall clock
|
||
# - sync --all is one async-fanout process; cron SIGKILL kills the whole
|
||
# process including sources not yet reached AND leaks the per-source
|
||
# lock for sources mid-import
|
||
# - next cron finds the stale lock + a bigger backlog and times out worse
|
||
# - sources late in the fan-out (media-corpus, straylight-brain) go 50+
|
||
# hours stale
|
||
#
|
||
# What v0.41.13.0 ships (the contract this test pins):
|
||
# 1. --timeout self-terminates each source gracefully (per-source budget
|
||
# via D-V3-3 AbortController inside runOne; per-iteration abort check
|
||
# in pull/delete/rename/import per D-V3-2 + D-V4-2).
|
||
# 2. --break-lock --all --max-age 1800 cron-self-heals across all sources
|
||
# via the new last_refreshed_at semantic (D-V3-4 / D-V4-1).
|
||
# 3. partial status preserves last_commit so next cron re-walks the
|
||
# same diff and content_hash short-circuits already-imported files.
|
||
#
|
||
# This test simulates the cascade-recovery flow by:
|
||
# - Creating 4 in-memory PGLite "sources" backed by tiny git fixtures.
|
||
# - Running 3 sequential sync waves with --timeout set tight enough that
|
||
# at least one wave per source hits the partial path.
|
||
# - Asserting every source reaches `last_commit === HEAD` within 3 waves.
|
||
#
|
||
# This is NOT a Postgres test (PGLite forces serial sync internally — see
|
||
# `parallelEligible` at sync.ts) but it exercises the per-source
|
||
# AbortController + partial-status threading + post-partial resume which
|
||
# are the load-bearing v4 changes. The Postgres parallel-fan-out case
|
||
# lives in test/e2e/sync-parallel.test.ts (D-V4-mech-10).
|
||
#
|
||
# Usage:
|
||
# tests/heavy/sync_timeout_rescue.sh # quick run
|
||
# PAGES=500 WAVES=3 TIMEOUT_SECONDS=2 tests/heavy/sync_timeout_rescue.sh
|
||
#
|
||
# Env vars:
|
||
# PAGES pages per source (default 200)
|
||
# WAVES sync waves to run (default 3)
|
||
# TIMEOUT_SECONDS --timeout value per wave (default 5)
|
||
# STRICT 1 = fail if any source isn't current by WAVES waves
|
||
# 0 = informational (default 1)
|
||
|
||
set -euo pipefail
|
||
|
||
cd "$(dirname "$0")/../.."
|
||
|
||
PAGES="${PAGES:-200}"
|
||
WAVES="${WAVES:-3}"
|
||
TIMEOUT_SECONDS="${TIMEOUT_SECONDS:-5}"
|
||
STRICT="${STRICT:-1}"
|
||
|
||
LOG_DIR="${GBRAIN_HOME:-$HOME/.gbrain}/audit"
|
||
mkdir -p "$LOG_DIR"
|
||
TS=$(date -u +%Y%m%d-%H%M%SZ)
|
||
WORKLOAD_OUT="$LOG_DIR/heavy-sync_timeout_rescue-$TS.json"
|
||
|
||
echo "[sync_timeout_rescue] pages=$PAGES waves=$WAVES timeout=${TIMEOUT_SECONDS}s strict=$STRICT"
|
||
echo "[sync_timeout_rescue] running cascade-recovery simulation..."
|
||
|
||
unset DATABASE_URL || true
|
||
set +e
|
||
timeout 600s env \
|
||
PAGES="$PAGES" \
|
||
WAVES="$WAVES" \
|
||
TIMEOUT_SECONDS="$TIMEOUT_SECONDS" \
|
||
STRICT="$STRICT" \
|
||
bun run tests/heavy/_sync_timeout_rescue_workload.ts > "$WORKLOAD_OUT" 2>>"$LOG_DIR/heavy-sync_timeout_rescue-stderr-$TS.log"
|
||
WORKLOAD_RC=$?
|
||
set -e
|
||
|
||
if [ "$WORKLOAD_RC" -ne 0 ]; then
|
||
echo "[sync_timeout_rescue] FAIL: workload exited $WORKLOAD_RC" >&2
|
||
cat "$WORKLOAD_OUT" >&2 2>/dev/null || true
|
||
echo " See $LOG_DIR/heavy-sync_timeout_rescue-stderr-$TS.log for stderr." >&2
|
||
exit 1
|
||
fi
|
||
|
||
cat "$WORKLOAD_OUT"
|
||
echo "[sync_timeout_rescue] PASS — every source converged within $WAVES waves."
|