fix: QA remediation P1-A/P1-B/P1-C/P2 for v0.22.1 sync-mode
P1-A: wrap wp_schedule_single_event(GENERATE_ACTION) + fire_cron_now() in on_orchestrate_tick() with 'if ( ! self::$sync_mode )' guard. Mirrors the existing guard in on_generate_tick(). Prevents a background wp-cron process spawning in parallel with the VPS --sync loop and prematurely finalizing the run lock before Article_Worker completes. P1-B: add two unit tests to GenerationCheckpointRunnerTest.php: - test_orchestrate_tick_in_sync_mode_does_not_schedule_background_event: asserts sync_mode=true suppresses GENERATE_ACTION schedule + spawn_cron. - test_generate_tick_async_mode_schedules_generate_action: asserts sync_mode=false (async path) still reschedules GENERATE_ACTION. P1-C: create root CONTEXT.md with domain glossary (run, run_stages, checkpoint, idea queue, Generation_Lock) and execution mode reference (async wp-cron vs --sync VPS-driven). P2: update ARCHITECTURE.md §25 Entry Points table with the 'wp prautoblogger generate --sync' VPS path row. Agent-Session: prab-reliability-remediation-20260622
This commit is contained in:
77
CONTEXT.md
Normal file
77
CONTEXT.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# PRAutoBlogger — Domain Glossary
|
||||
|
||||
Quick reference for the generation pipeline domain model. For full design rationale
|
||||
see `ARCHITECTURE.md` (§21–§25) and `CONVENTIONS.md`.
|
||||
|
||||
---
|
||||
|
||||
## Core Domain Terms
|
||||
|
||||
**run**
|
||||
A single end-to-end article generation cycle: orchestrate → generate idea(s) →
|
||||
finalize. Represented as a row in `wp_prautoblogger_runs` (status, cost ceiling,
|
||||
timestamps). One run may produce multiple articles if the daily idea-count > 1.
|
||||
|
||||
**run\_stages** (`wp_prautoblogger_run_stages`)
|
||||
Sub-steps within a run (research, analysis, generation, publish). Each stage has
|
||||
its own status and can be replayed independently via `Rerun_Executor`. Generation
|
||||
checkpoint runs populate stages as Article_Worker progresses.
|
||||
|
||||
**checkpoint**
|
||||
The persistence boundary between pipeline ticks. After each tick the idea queue
|
||||
and run state are written to `wp_options` so a process kill cannot lose work. The
|
||||
next tick reads the queue option and continues. See §25 of ARCHITECTURE.md.
|
||||
|
||||
**idea queue** (`prautoblogger_article_queue` option)
|
||||
Serialized array of `Article_Idea` objects written by `on_orchestrate_tick()` and
|
||||
consumed one-at-a-time by successive `on_generate_tick()` calls. Deleted on
|
||||
finalize or cleanup.
|
||||
|
||||
**Generation\_Lock** (`wp_prautoblogger_generation_lock` or `wp_options`)
|
||||
DB mutex that prevents two concurrent runs. Acquired at the start of
|
||||
`on_orchestrate_tick()`, released by `Helpers::finalize()` or on error/halt.
|
||||
|
||||
---
|
||||
|
||||
## Execution Modes
|
||||
|
||||
### Async (wp-cron driven)
|
||||
|
||||
Default path for the Board "New Article" button and the plain
|
||||
`wp prautoblogger generate` WP-CLI command.
|
||||
|
||||
1. `kick_off()` schedules `prautoblogger_gen_orchestrate` and calls `fire_cron_now()`.
|
||||
2. `on_orchestrate_tick()` runs in a background PHP process, schedules
|
||||
`prautoblogger_gen_tick`, and calls `fire_cron_now()` to spawn the next process.
|
||||
3. Each `on_generate_tick()` spawns the next until the queue drains.
|
||||
|
||||
Limitation: Hostinger kills background PHP processes at ~10 min. Orchestrate tick
|
||||
(LLM-free) and individual generate ticks (one LLM call each) are both well within
|
||||
this limit; the checkpoint design is the mitigation.
|
||||
|
||||
### Sync (VPS-driven / `--sync`)
|
||||
|
||||
Used by the Coolify KVM8 VPS systemd timer via `infra/vps/orchestrate-generation.sh`
|
||||
in `peptide-e2e`. Introduced v0.22.1.
|
||||
|
||||
1. `run_sync()` sets `Generation_Checkpoint_Runner::$sync_mode = true`.
|
||||
2. Calls `on_orchestrate_tick()` **in-process** (no background spawn).
|
||||
3. Loops calling `on_generate_tick()` directly until queue empty or terminal state.
|
||||
4. `$sync_mode = true` suppresses all `wp_schedule_single_event` +
|
||||
`fire_cron_now` calls inside both tick methods, preventing a competing
|
||||
background cron chain from forming in parallel.
|
||||
|
||||
The VPS SSH session is held open; the process is not subject to Hostinger's
|
||||
background-kill constraint.
|
||||
|
||||
---
|
||||
|
||||
## Table Shorthand
|
||||
|
||||
Throughout the codebase `wp_prautoblogger_*` tables are referenced by their
|
||||
`$wpdb->` property names (e.g. `$wpdb->prab_runs`, `$wpdb->prab_run_stages`).
|
||||
Full table names are defined in `class-activator.php`.
|
||||
|
||||
---
|
||||
|
||||
*See also: `ARCHITECTURE.md` §25 (checkpoint design), `CONVENTIONS.md` (coding rules).*
|
||||
Reference in New Issue
Block a user