feat(prompts): versioned prompt registry, v1 seed, pinning + stamping
Pipeline v2 Phase 1, commit 2/4. Prompt_Registry (read) + Prompt_Registry_Writer (immutable create/activate/seed) over the new prompts table; canonical v1 bodies extracted verbatim into Prompt_Defaults(+Editorial) — single source for BOTH the seed migration (Migrate_Prompt_Seed_V0180, flag-gated, self-healing) and the in-code fallback, so a missing table renders byte-identical prompts and never fatals. Call sites swapped: Content_Prompts, Analysis_Prompts, Chief_Editor, LLM_Research_Provider. Includes the image-composer seam keys image.rewriter_system + image.style_template (composer PR consumes, must not add its own prompt storage). Pinning: Cost_Tracker::set_run_id() registers the process run context, ensures the runs ledger row, and pins active versions once per run; log_api_call/log_image_generation stamp prompt_version (run pins) + agent_role (stage map) on every generation_log row. Single-pass keeps stage 'draft' and stamps content.single_pass explicitly. Under-300 refactors: Content_Generator's four duplicated span/log blocks consolidated into execute_stage() (301 -> 224 lines, behavior identical); get_avg_tokens_for_stages body moved to Cost_Reporter with a delegating wrapper kept for API compatibility. Tests: byte-identical fallback renders (single_pass/outline/polish/ editor.system), token filling, key coverage incl. stage-map integrity. Agent-Session: pipeline-v2-phase1-engineer-20260612
This commit is contained in:
peptiderepo
259
includes/core/class-run-state.php
Normal file
259
includes/core/class-run-state.php
Normal file
@@ -0,0 +1,259 @@
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
|
||||
*
|
||||
* Run-level state: the `wp_prautoblogger_runs` ledger + lifecycle row.
|
||||
*
|
||||
* What: One row per pipeline run (keyed by run_id UUID) carrying the run
|
||||
* status (pending|running|done|failed|halted), the per-run cost
|
||||
* ledger the Cost_Governor reserves against (ceiling / reserved /
|
||||
* settled / overage), and the prompt versions pinned at run start.
|
||||
* Every method is self-healing: a missing table (half-migrated
|
||||
* site) degrades to no-ops/empty reads, never a fatal. Final states
|
||||
* are sticky — a halted or failed run cannot be flipped back to
|
||||
* running by a late writer. Per-stage state lives in
|
||||
* PRAutoBlogger_Run_Stage_State (run_stages table).
|
||||
* Who triggers it: Cost_Tracker::set_run_id() (ensure_run + pinning),
|
||||
* Cost_Governor (ledger + halt), Run_Reaper (stuck-run sweep),
|
||||
* Review Queue (halted-run surfacing), Pipeline_Runner (completion).
|
||||
* Dependencies: WordPress $wpdb, get_option (ceiling setting), wp_json_encode.
|
||||
*
|
||||
* @see core/class-cost-governor.php — Reserves against this row atomically.
|
||||
* @see core/class-prompt-registry.php — Reads/writes pins via this class.
|
||||
* @see core/class-run-stage-state.php — Per-stage rows (commit 4).
|
||||
* @see ARCHITECTURE.md #21 — Design rationale.
|
||||
*/
|
||||
class PRAutoBlogger_Run_State {
|
||||
|
||||
/** @var bool|null Per-request "runs table exists" probe result. */
|
||||
private static ?bool $table_ok = null;
|
||||
|
||||
/** Fully-qualified runs table name (shared with Cost_Governor). */
|
||||
public static function table_name(): string {
|
||||
global $wpdb;
|
||||
return $wpdb->prefix . 'prautoblogger_runs';
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the runs table exists and is queryable. Cached per request;
|
||||
* never throws.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public static function is_available(): bool {
|
||||
if ( null !== self::$table_ok ) {
|
||||
return self::$table_ok;
|
||||
}
|
||||
global $wpdb;
|
||||
if ( null === $wpdb ) {
|
||||
return false; // Not cached: $wpdb may appear later in boot.
|
||||
}
|
||||
$table = self::table_name();
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
|
||||
$found = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) );
|
||||
self::$table_ok = ( $found === $table );
|
||||
return self::$table_ok;
|
||||
}
|
||||
|
||||
/**
|
||||
* The per-run cost ceiling, read from the SETTING at call time
|
||||
* (never a literal at the point of use). 0 disables the per-run guard.
|
||||
*
|
||||
* @return float Ceiling in USD.
|
||||
*/
|
||||
public static function ceiling_setting(): float {
|
||||
return (float) get_option( 'prautoblogger_per_run_cost_ceiling_usd', PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD );
|
||||
}
|
||||
|
||||
/**
|
||||
* Create the run row if it does not exist (INSERT IGNORE — concurrent
|
||||
* callers cannot double-create). Snapshots the ceiling setting at run
|
||||
* start so a mid-run settings change cannot move the goalposts.
|
||||
*
|
||||
* Side effects: one INSERT IGNORE.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @return void
|
||||
*/
|
||||
public static function ensure_run( string $run_id ): void {
|
||||
if ( '' === $run_id || ! self::is_available() ) {
|
||||
return;
|
||||
}
|
||||
global $wpdb;
|
||||
$table = self::table_name();
|
||||
$now = current_time( 'mysql' );
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
|
||||
$wpdb->query(
|
||||
$wpdb->prepare(
|
||||
"INSERT IGNORE INTO {$table}
|
||||
(run_id, status, ceiling_usd, reserved_usd, settled_usd, overage_usd, started_at, updated_at)
|
||||
VALUES (%s, 'running', %f, 0, 0, 0, %s, %s)",
|
||||
$run_id,
|
||||
self::ceiling_setting(),
|
||||
$now,
|
||||
$now
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch a run row.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @return array<string, mixed>|null Row, or null when absent/unavailable.
|
||||
*/
|
||||
public static function get_run( string $run_id ): ?array {
|
||||
if ( '' === $run_id || ! self::is_available() ) {
|
||||
return null;
|
||||
}
|
||||
global $wpdb;
|
||||
$table = self::table_name();
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
|
||||
$row = $wpdb->get_row(
|
||||
$wpdb->prepare( "SELECT * FROM {$table} WHERE run_id = %s", $run_id ),
|
||||
ARRAY_A
|
||||
);
|
||||
return is_array( $row ) ? $row : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Current run status, or null when the run has no row.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @return string|null pending|running|done|failed|halted, or null.
|
||||
*/
|
||||
public static function get_status( string $run_id ): ?string {
|
||||
$run = self::get_run( $run_id );
|
||||
return null !== $run ? (string) $run['status'] : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Store the pinned prompt versions — only if the run has none yet, so
|
||||
* a resumed run keeps the versions it started with.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @param array<string, int> $pins prompt_key => version map.
|
||||
* @return void
|
||||
*/
|
||||
public static function set_pins_if_absent( string $run_id, array $pins ): void {
|
||||
if ( '' === $run_id || empty( $pins ) || ! self::is_available() ) {
|
||||
return;
|
||||
}
|
||||
self::ensure_run( $run_id );
|
||||
global $wpdb;
|
||||
$table = self::table_name();
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
|
||||
$wpdb->query(
|
||||
$wpdb->prepare(
|
||||
"UPDATE {$table} SET pinned_prompts_json = %s, updated_at = %s
|
||||
WHERE run_id = %s AND (pinned_prompts_json IS NULL OR pinned_prompts_json = '')",
|
||||
wp_json_encode( $pins ),
|
||||
current_time( 'mysql' ),
|
||||
$run_id
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The pinned prompt versions for a run.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @return array<string, int> prompt_key => version ({} when none).
|
||||
*/
|
||||
public static function get_pins( string $run_id ): array {
|
||||
$run = self::get_run( $run_id );
|
||||
if ( null === $run || empty( $run['pinned_prompts_json'] ) ) {
|
||||
return array();
|
||||
}
|
||||
$pins = json_decode( (string) $run['pinned_prompts_json'], true );
|
||||
return is_array( $pins ) ? array_map( 'intval', $pins ) : array();
|
||||
}
|
||||
|
||||
/**
|
||||
* Move a run to a new status. Forward transitions only touch open
|
||||
* (pending/running) runs; `halted` and `failed` are sticky and `done`
|
||||
* cannot overwrite them.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @param string $status One of done|failed|halted|running.
|
||||
* @return bool True when a row transitioned.
|
||||
*/
|
||||
public static function mark_status( string $run_id, string $status ): bool {
|
||||
if ( '' === $run_id || ! self::is_available() ) {
|
||||
return false;
|
||||
}
|
||||
if ( ! in_array( $status, array( 'running', 'done', 'failed', 'halted' ), true ) ) {
|
||||
return false;
|
||||
}
|
||||
global $wpdb;
|
||||
$table = self::table_name();
|
||||
$now = current_time( 'mysql' );
|
||||
$finished = in_array( $status, array( 'done', 'failed', 'halted' ), true ) ? $now : null;
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
|
||||
$updated = $wpdb->query(
|
||||
$wpdb->prepare(
|
||||
"UPDATE {$table} SET status = %s, updated_at = %s, finished_at = %s
|
||||
WHERE run_id = %s AND status IN ('pending','running')",
|
||||
$status,
|
||||
$now,
|
||||
$finished,
|
||||
$run_id
|
||||
)
|
||||
);
|
||||
return $updated >= 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record by how much a breaching reservation exceeded the ceiling.
|
||||
*
|
||||
* @param string $run_id Pipeline run UUID.
|
||||
* @param float $overage USD amount over the ceiling.
|
||||
* @return void
|
||||
*/
|
||||
public static function record_overage( string $run_id, float $overage ): void {
|
||||
if ( '' === $run_id || $overage <= 0 || ! self::is_available() ) {
|
||||
return;
|
||||
}
|
||||
global $wpdb;
|
||||
$table = self::table_name();
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
|
||||
$wpdb->query(
|
||||
$wpdb->prepare(
|
||||
"UPDATE {$table} SET overage_usd = GREATEST(overage_usd, %f), updated_at = %s WHERE run_id = %s",
|
||||
$overage,
|
||||
current_time( 'mysql' ),
|
||||
$run_id
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Recent halted runs, for the Review Queue surface.
|
||||
*
|
||||
* @param int $limit Max rows (default 10).
|
||||
* @return array<int, array<string, mixed>>
|
||||
*/
|
||||
public static function halted_runs( int $limit = 10 ): array {
|
||||
if ( ! self::is_available() ) {
|
||||
return array();
|
||||
}
|
||||
global $wpdb;
|
||||
$table = self::table_name();
|
||||
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
|
||||
$rows = $wpdb->get_results(
|
||||
$wpdb->prepare(
|
||||
"SELECT * FROM {$table} WHERE status = 'halted' ORDER BY updated_at DESC LIMIT %d",
|
||||
$limit
|
||||
),
|
||||
ARRAY_A
|
||||
);
|
||||
return is_array( $rows ) ? $rows : array();
|
||||
}
|
||||
|
||||
/** Reset per-request caches (tests). */
|
||||
public static function flush_cache(): void {
|
||||
self::$table_ok = null;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user