AI -> validate -> render -> check pipeline. */ interface GeneratorInterface { /** * Run the full pipeline for one subject: plan -> compile -> call -> * validate (+ bounded repair) -> render -> checks -> eligibility. * * `$ctx` contract (every key present; optional values are null, not * missing): * - generator string One of `Generators::all()`. * - definition array Normalized BlueprintDefinition (DefinitionNormalizer's output), for THIS generator. * - brandProfile array|null BrandProfileData, already pinned to its snapshot revision; null when no profile is assigned. * - subject array{type:string,id:int,label:string} 'product' | 'term' | 'attachment'. * - product \WC_Product|null Set when subject.type is 'product' (or 'attachment', for its parent product). * - term \WP_Term|null Set when subject.type is 'term'. * - images array Attachment ids/positions for `image_alt` generators; empty otherwise. * - sources array `SourceContentProviderInterface::contentForSubject()`'s result, keyed by source id. * - decisions array `DecisionStore` rows for this subject (source-conflict acceptances). * - runOptions array{companions:array{shortDescription:bool,tags:bool},language:string,provider:string,model:string,allowExistingDescription:bool,excludeQuestions:string[]} * - conflictDetector callable|null `ConflictDetector::detect()`'s signature; null disables conflict detection. * - deadline float Unix timestamp; no new provider call may start at/after this. * - maxCalls int Total provider-call budget for this generation (default 3). * * @param array $ctx Execution context, see above. * @param StructuredCallerInterface $caller Structured AI caller. * @return array{units:array,outputs:array,checks:array,conflicts:array,findings:array,sourcesUsed:array,eligibility:array,usage:array,providerError:array|null} The generator-specific slice of GenerationResult. `providerError` is the first terminal provider-call failure of this run (code, reason, message, provider), or null when none occurred. */ public function generate( array $ctx, StructuredCallerInterface $caller ): array; /** * Re-run exactly one AI unit with the same spec and context, then * re-run cross-unit checks (duplicate sentences, the banned-phrase and * section-order measured checks, eligibility) over the merged result. * Every other unit's content is reused verbatim from `$previous`. * * Calling this for a unit that is not AI mode, or whose current plan * status needs no model call (disabled/skipped/fixed/data), is a no-op * that returns `$previous` unchanged - there is nothing to regenerate. * * @param array $ctx Execution context, see generate(). * @param array $previous The generator-specific slice generate() previously returned. * @param string $unit_id The unit id to regenerate. * @param StructuredCallerInterface $caller Structured AI caller. * @return array Same shape as generate()'s return value. */ public function regenerateUnit( array $ctx, array $previous, string $unit_id, StructuredCallerInterface $caller ): array; }