$blueprint_items `BlueprintSourcePolicy.items`, priority order. * @param array $provider_results `SourceContentProviderInterface::contentForSubject()`'s * result, keyed by source id. * @return array{ * blocks: array,status:string,usable:bool,contentVersion:int}>, * sourcesUsed: array * } */ public function build( array $blueprint_items, array $provider_results ): array { $blocks = array(); $sources_used = array(); $budget = self::TOTAL_CHAR_CAP; foreach ( $blueprint_items as $item ) { $ref = is_array( $item ) ? (string) ( $item['ref'] ?? '' ) : ''; if ( 'product' === $ref || '' === $ref || empty( $item['enabled'] ) ) { continue; } if ( 1 !== preg_match( '/^src:(\d+)$/', $ref, $matches ) ) { continue; } $id = (int) $matches[1]; $entry = $provider_results[ $id ] ?? null; if ( null === $entry || ! is_array( $entry ) ) { continue; } $status = (string) ( $entry['status'] ?? 'error' ); $usable = ! empty( $entry['usable'] ); $name = (string) ( $entry['name'] ?? $ref ); $version = (int) ( $entry['contentVersion'] ?? 0 ); $sources_used[] = array( 'ref' => $ref, 'name' => $name, 'status' => $status, 'contentVersion' => $version, ); $text = ''; $facts = array(); if ( $usable && is_array( $entry['extracted'] ?? null ) ) { $facts = $this->selectFactsWithinBudget( $this->normalizeFacts( $entry['extracted']['facts'] ?? array() ), min( self::PER_SOURCE_CHAR_CAP, max( 0, $budget ) ) ); $facts_len = $this->factsLineLength( $facts ); $budget -= $facts_len; $remaining_source_cap = max( 0, self::PER_SOURCE_CHAR_CAP - $facts_len ); $capped = $this->capText( (string) ( $entry['extracted']['text'] ?? '' ), $remaining_source_cap ); $text = $this->takeFromBudget( $capped, $budget ); $budget -= mb_strlen( $text, 'UTF-8' ); } $blocks[] = array( 'ref' => $ref, 'id' => $id, 'name' => $name, 'priority' => count( $blocks ), 'text' => $text, 'facts' => $facts, 'status' => $status, 'usable' => $usable, 'contentVersion' => $version, ); } return array( 'blocks' => $blocks, 'sourcesUsed' => $sources_used, ); } /** * The ordered list of refs one section may use: its own local selection * when it does not inherit, otherwise the blueprint's own priority order * (enabled items only). `'product'` is a valid member of both. * * @param array{inherit:bool,refs:string[]} $section_sources `BlueprintSection.sources`. * @param array $blueprint_items `BlueprintSourcePolicy.items`, priority order. * @return string[] */ public function refsForSection( array $section_sources, array $blueprint_items ): array { if ( empty( $section_sources['inherit'] ) ) { return array_values( array_map( 'strval', (array) ( $section_sources['refs'] ?? array() ) ) ); } $refs = array(); foreach ( $blueprint_items as $item ) { if ( ! empty( $item['enabled'] ) ) { $refs[] = (string) ( $item['ref'] ?? '' ); } } return array_values( array_filter( $refs ) ); } /** * $blocks filtered to the refs a section may use AND currently usable, * preserving $blocks' own (blueprint priority) order. * * @param array $blocks build()'s `blocks`. * @param string[] $refs refsForSection()'s result. * @return array */ public function usableBlocksForRefs( array $blocks, array $refs ): array { $allowed = array_fill_keys( $refs, true ); return array_values( array_filter( $blocks, static function ( $block ) use ( $allowed ) { return ! empty( $block['usable'] ) && isset( $allowed[ $block['ref'] ] ); } ) ); } /** * Flat `{ref,label,value}` source facts for every usable block, for the * injected conflict detector. * * @param array $blocks build()'s `blocks`. * @return array */ public function flattenFacts( array $blocks ): array { $flat = array(); foreach ( $blocks as $block ) { if ( empty( $block['usable'] ) ) { continue; } foreach ( (array) $block['facts'] as $fact ) { $flat[] = array( 'ref' => $block['ref'], 'label' => (string) ( $fact['label'] ?? '' ), 'value' => (string) ( $fact['value'] ?? '' ), ); } } return $flat; } /** * Keep as many facts (in order) as fit within `$max_len`, measured the * same way `PromptCompiler` renders them ("Label: value" lines, joined * by "\n") — so the reserved budget here always matches what the * compiled prompt actually spends. Facts are never partially cut mid * line; a fact that would not fit is dropped whole, together with * every fact after it (budget-priority order is already the * extraction's own order). * * @param array $facts Already-normalized facts. * @param int $max_len Maximum combined length. * @return array */ private function selectFactsWithinBudget( array $facts, int $max_len ): array { if ( $max_len <= 0 ) { return array(); } $selected = array(); foreach ( $facts as $fact ) { $candidate = $selected; $candidate[] = $fact; if ( $this->factsLineLength( $candidate ) > $max_len ) { break; } $selected = $candidate; } return $selected; } /** * @param array $facts Facts. * @return int Character length of their "Label: value" lines, joined by "\n". */ private function factsLineLength( array $facts ): int { return mb_strlen( implode( "\n", array_map( static function ( $fact ) { return $fact['label'] . ': ' . $fact['value']; }, $facts ) ), 'UTF-8' ); } /** * @param string[] $facts Raw extracted facts. * @return array */ private function normalizeFacts( $facts ): array { if ( ! is_array( $facts ) ) { return array(); } $normalized = array(); foreach ( $facts as $fact ) { if ( ! is_array( $fact ) ) { continue; } $label = trim( (string) ( $fact['label'] ?? '' ) ); $value = trim( (string) ( $fact['value'] ?? '' ) ); if ( '' === $label || '' === $value ) { continue; } $normalized[] = array( 'label' => $label, 'value' => $value ); } return $normalized; } /** * @param string $text Raw text. * @param int $max_len Maximum characters. * @return string */ private function capText( string $text, int $max_len ): string { return mb_substr( $text, 0, $max_len, 'UTF-8' ); } /** * Take as much of $text as the remaining $budget allows. * * @param string $text Text already capped per-source. * @param int $budget Remaining total-budget characters. * @return string */ private function takeFromBudget( string $text, int $budget ): string { if ( $budget <= 0 ) { return ''; } return mb_substr( $text, 0, $budget, 'UTF-8' ); } }