a broader * assignment that reaches the subject (`target_type='category'` matching * one of the product's own categories, or any ancestor category when * `include_children` is set, for a product or attachment subject; * `target_type='taxonomy'` matching the subject term's own taxonomy, for * the taxonomy generator) > the generator's store default > the generator's * built-in default template. A product-level or per-term assignment row is * never consulted: only a category exception (product generators) or a * whole-taxonomy row (`target_id` 0; the taxonomy generator's "tags" slot) * can win above the store default. * * The broader tier can have more than one matching row for a product * subject (several category rows reaching the same product); the taxonomy * generator's tier never can, because the assignments table's UNIQUE key * allows at most one `target_type='taxonomy'` row per (generator, * taxonomy). Within the tier, the lowest `priority` number wins; if two or * more DIFFERENT blueprint ids are tied at the winning priority, that is a * conflict (`blueprintId: null`) and nothing below it is considered. The * same blueprint id appearing more than once at the winning priority is not * a conflict. A row whose blueprint no longer exists (live mode) or has no * snapshot (pinned mode) is skipped from the competition and noted on the * step, never silently miscounted as a normal miss. * * Live vs pinned: with `$run_pin` omitted, every tier reads the current * `AssignmentStore` rows. With `$run_pin` given (a `kind='run'` execution * snapshot's `payload`), every tier reads ONLY * `$run_pin['assignments']` — a running or completed job's resolution can * never drift because someone edited assignments after it started. * * Free keeps exactly one store-wide structure per content type. Category * exceptions and the Product tags structure are Business: this class still * finds the stored rows that reach the subject (so "Where it's used" can * describe them and a run can say one was skipped), but which of them * applies is decided by the Business build, through the * {@see TIER_FILTER} filter (the lowest priority wins; a tie between * different structures is a conflict). Without a decision, matching rows * are reported 'locked' rather than applied, and resolution falls through * to the store default or built-in template instead. The row itself is * never touched here; only this run's outcome changes. * * A caller resolving many subjects for the same generator in one request * (e.g. {@see \AIPT\Core\ContentStructure\Assignment\AssignmentScope::resolveForProducts()}) * should fetch the rows once and pass them as `$preloaded_rows`, instead of * letting every call re-query `AssignmentStore::listForGenerator()`. */ class AssignmentResolver { /** * Filter deciding Step 2 among the usable rows that reach the subject: * receives null and those rows, and returns * array{winner: array|null, conflict: array|null} (one of the rows, or * array{priority:int,blueprintIds:int[],message:string}), or null to * leave the tier unapplied. */ public const TIER_FILTER = 'aipt_content_structure_assignment_tier'; /** * @var BlueprintStore */ private $blueprints; /** * @var AssignmentStore */ private $assignments; /** * @var ExecutionSnapshotStore */ private $snapshots; /** * Per-resolve() cache of blueprint existence/name lookups in live mode, * so a tier with several competing rows does not repeat the same * `BlueprintStore::get()` call. Reset at the start of every resolve(). * * @var array|false> */ private $blueprint_cache = array(); /** * Per-resolve() cache of pinned-mode definition-snapshot lookups (for * {@see blueprintName()}), keyed by snapshot id. Reset at the start of * every resolve(), same reasoning as $blueprint_cache. * * @var array|null> */ private $pinned_name_cache = array(); /** * Per-instance memo of Step 4's built-in default template name, keyed by * ":