<?php
/**
 * Engine: the seam. A consuming plugin passes one object implementing this
 * interface to SSAA_Engine::boot(). The engine calls only these methods;
 * it never references a consumer's own classes. This is the injected
 * config + handler seam from RENDER-ENGINE.md (chosen over WordPress filters
 * so the two distinct queue processors live in one explicit contract).
 *
 * CANONICAL ENGINE SOURCE - edit here in _shared/shared-render-engine/src/, re-run
 * sync.sh. The SSAA_Engine prefix and search-social-appearance-audit text domain
 * are rewritten per-consumer at sync time.
 *
 * @package plugupp-render-engine
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

interface SSAA_Engine_Handler {

	/**
	 * Return the full set of page descriptors a scan should cover.
	 *
	 * A descriptor is an associative array:
	 *   array(
	 *     'kind'  => 'post' | 'url',
	 *     'ref'   => int (post ID) | string (absolute URL),
	 *     'type'  => string (post type, or 'home'|'tax'|'date'|... for url),
	 *     'label' => string (human label for logs / progress),
	 *     // optional: 'permalink', and any consumer-private payload.
	 *   )
	 *
	 * The engine provides SSAA_Engine_Discovery::post_descriptors() as the
	 * post/page half; a typical handler returns that plus its own synthesized
	 * non-post descriptors, then drops excluded refs via
	 * SSAA_Engine_Exclusions::filter_descriptors().
	 *
	 * @return array[] List of descriptors.
	 */
	public function discover();

	/**
	 * Process one page descriptor: render it (via SSAA_Engine_Renderer),
	 * run the consumer's analyzer over the HTML, persist results, and register
	 * any newly-seen unique URLs for a later phase.
	 *
	 * @param array $descriptor One descriptor from discover().
	 * @return array Outcome: array(
	 *     'status'      => 'ok'|'error'|'gone',
	 *     'retryable'   => bool,
	 *     'error_code'  => string (optional),
	 *     'http_status' => int (optional),
	 * )
	 */
	public function process_page( array $descriptor );

	/**
	 * Process one batch of items from a second (or later) queue. For LIHA this
	 * is a batch of unique URLs to check; the engine treats the batch as an
	 * opaque queue item and only requires the standard outcome shape back.
	 *
	 * @param array $batch One queue item (e.g. a list of URLs).
	 * @return array Outcome with the same shape as process_page().
	 */
	public function process_url_batch( array $batch );

	/**
	 * A descriptor's target no longer exists (post deleted since the queue was
	 * built). The consumer should drop any stored rows for it.
	 *
	 * @param string $ref Engine ref ('post:ID' or 'url:hash').
	 * @return void
	 */
	public function on_item_gone( $ref );

	/**
	 * Refs were added to the engine exclusion store. The consumer should drop
	 * its stored result rows for them (store + discovery filter are engine
	 * owned; only this persistence effect is delegated).
	 *
	 * @param string[] $refs Engine refs newly excluded.
	 * @return void
	 */
	public function on_items_excluded( array $refs );

	/**
	 * Refs were removed from the exclusion store. They reappear after the next
	 * scan; most consumers need no immediate action here.
	 *
	 * @param string[] $refs Engine refs re-included.
	 * @return void
	 */
	public function on_items_reincluded( array $refs );
}
