blueprints = $blueprints ?? new BlueprintStore(); $this->brand_profiles = $brand_profiles ?? new BrandProfileStore(); $this->sources = $sources ?? new SourceStore(); $this->assignments = $assignments ?? new AssignmentStore(); $this->snapshots = $snapshots ?? new ExecutionSnapshotStore(); } /** * Freeze one generator's current assignment rows plus a definition * snapshot for every Blueprint they (or the manual pick) reference, and * for the built-in default template. * * @param string $generator Generator key. * @param int|null $manual_blueprint_id A manually-picked Blueprint for this run, or null. * @param int $user_id Acting user id. * @return array{id:int,hash:string,generator:string,manualBlueprintId:int|null,blueprints:array,createdAt:string,payload:array} RunPin plus its raw `payload`. */ public function createRunPin( string $generator, ?int $manual_blueprint_id, int $user_id ): array { $rows = $this->assignments->listForGenerator( $generator ); $referenced_ids = array(); if ( null !== $manual_blueprint_id && $manual_blueprint_id > 0 ) { $referenced_ids[ $manual_blueprint_id ] = true; } foreach ( $rows as $row ) { $blueprint_id = (int) ( $row['blueprintId'] ?? 0 ); if ( $blueprint_id > 0 ) { $referenced_ids[ $blueprint_id ] = true; } } $definition_snapshots = array(); $blueprint_entries = array(); foreach ( array_keys( $referenced_ids ) as $blueprint_id ) { $snapshot = $this->snapshotForBlueprint( $blueprint_id, $user_id ); if ( is_wp_error( $snapshot ) ) { continue; } $definition_snapshots[ (string) $blueprint_id ] = $snapshot['id']; $blueprint_entries[] = array( 'id' => $blueprint_id, 'name' => (string) ( $snapshot['payload']['blueprint']['name'] ?? '' ), 'revision' => (int) ( $snapshot['payload']['blueprint']['revision'] ?? 0 ), ); } $builtin = $this->builtinSnapshot( $generator, $user_id ); $created_at = current_time( 'mysql', true ); $payload = array( 'generator' => $generator, 'manualBlueprintId' => $manual_blueprint_id, 'assignments' => $rows, 'definitionSnapshots' => $definition_snapshots, 'builtinDefault' => array( 'templateKey' => TemplateCatalog::defaultKey( $generator ), 'definitionSnapshotId' => $builtin['id'], ), ); $result = $this->snapshots->findOrCreate( 'run', $generator, $payload, array( 'createdBy' => $user_id ) ); $this->snapshots->touch( $result['id'] ); return array( 'id' => $result['id'], 'hash' => $result['hash'], 'generator' => $generator, 'manualBlueprintId' => $manual_blueprint_id, 'blueprints' => $blueprint_entries, 'createdAt' => $created_at, 'payload' => $payload, ); } /** * Whether a {@see createRunPin()} result is unusable — the id=0 signal * `ExecutionSnapshotStore::findOrCreate()` returns (already logged * there) when its insert genuinely failed, rather than a real snapshot * row. A caller about to start or hand out a pinned run must check this * first: proceeding with it would run unpinned against live data while * still showing the merchant a frozen revision, or hand out a pin id * that can never be loaded back. * * @param array{id:int} $pin {@see createRunPin()}'s result. * @return bool */ public static function pinFailed( array $pin ): bool { return (int) ( $pin['id'] ?? 0 ) <= 0; } /** * Load a previously created run pin by id or hash. * * @param int|string $id_or_hash Snapshot id, or its content hash. * @return array{id:int,hash:string,generator:string,manualBlueprintId:int|null,blueprints:array,createdAt:string,payload:array}|null */ public function loadRunPin( $id_or_hash ): ?array { $row = null; if ( is_int( $id_or_hash ) || ctype_digit( (string) $id_or_hash ) ) { $row = $this->snapshots->get( (int) $id_or_hash ); } if ( null === $row && is_string( $id_or_hash ) ) { $row = $this->snapshots->getByHash( $id_or_hash ); } if ( null === $row || 'run' !== $row['kind'] ) { return null; } $this->snapshots->touch( (int) $row['id'] ); $payload = $row['payload']; return array( 'id' => (int) $row['id'], 'hash' => (string) $row['hash'], 'generator' => (string) $row['generator'], 'manualBlueprintId' => isset( $payload['manualBlueprintId'] ) ? $payload['manualBlueprintId'] : null, 'blueprints' => $this->blueprintEntriesFromPayload( $payload ), 'createdAt' => (string) ( $payload['createdAt'] ?? $row['createdAt'] ?? '' ), 'payload' => $payload, ); } /** * Read one `kind='definition'` snapshot by id and mark it used. * * @param int $snapshot_id Snapshot id. * @return array|WP_Error The snapshot row, or `aipt_blueprint_pin_missing` when it does not exist or is not a definition snapshot. */ public function definitionSnapshot( int $snapshot_id ) { $row = $this->snapshots->get( $snapshot_id ); if ( null === $row || 'definition' !== $row['kind'] ) { return new WP_Error( 'aipt_blueprint_pin_missing', __( 'This run pin has no snapshot for the requested template.', 'ai-product-tools' ), array( 'status' => 404 ) ); } $this->snapshots->touch( $snapshot_id ); return $row; } /** * Find or create the `kind='definition'` snapshot for one Blueprint's * CURRENT saved revision. * * @param int $blueprint_id Blueprint id. * @param int $user_id Acting user id. * @return array{id:int,hash:string,payload:array}|WP_Error `aipt_blueprint_pin_missing` when the Blueprint no longer exists. */ public function snapshotForBlueprint( int $blueprint_id, int $user_id ) { $blueprint = $this->blueprints->get( $blueprint_id ); if ( null === $blueprint ) { return new WP_Error( 'aipt_blueprint_pin_missing', __( 'The selected template no longer exists.', 'ai-product-tools' ), array( 'status' => 404 ) ); } $definition = is_array( $blueprint['definition'] ) ? $blueprint['definition'] : array(); $brand_profile_id = (int) $blueprint['brandProfileId']; $brand_profile = null; $brand_revision = 0; if ( $brand_profile_id > 0 ) { $profile_row = $this->brand_profiles->get( $brand_profile_id ); if ( null !== $profile_row ) { $brand_profile = array( 'id' => (int) $profile_row['id'], 'name' => (string) $profile_row['name'], 'revision' => (int) $profile_row['revision'], 'profile' => $profile_row['profile'], ); $brand_revision = (int) $profile_row['revision']; } } $payload = array( 'blueprint' => array( 'id' => (int) $blueprint['id'], 'name' => (string) $blueprint['name'], 'generator' => (string) $blueprint['generator'], 'revision' => (int) $blueprint['revision'], 'definition' => $definition, 'definitionHash' => (string) $blueprint['definitionHash'], ), 'brandProfile' => $brand_profile, 'sources' => $this->sourcesForDefinition( $definition ), 'schemaVersion' => (int) ( $definition['schemaVersion'] ?? 1 ), 'rendererVersion' => Renderer::RENDERER_VERSION, ); $result = $this->snapshots->findOrCreate( 'definition', (string) $blueprint['generator'], $payload, array( 'blueprintId' => (int) $blueprint['id'], 'blueprintRevision' => (int) $blueprint['revision'], 'brandProfileId' => $brand_profile_id, 'brandRevision' => $brand_revision, 'createdBy' => $user_id, ) ); $this->snapshots->touch( $result['id'] ); return array( 'id' => $result['id'], 'hash' => $result['hash'], 'payload' => $payload ); } /** * Find or create the `kind='definition'` snapshot for a generator's * built-in default template (used when no Blueprint applies at all). * * @param string $generator Generator key. * @param int $user_id Acting user id. * @return array{id:int,hash:string,payload:array} */ public function builtinSnapshot( string $generator, int $user_id ): array { $template_key = TemplateCatalog::defaultKey( $generator ); $template = TemplateCatalog::get( $generator, $template_key ); $definition = null !== $template ? $template['definition'] : TemplateCatalog::defaultDefinition( $generator ); $payload = array( 'blueprint' => array( 'id' => 0, 'name' => null !== $template ? (string) $template['name'] : $template_key, 'generator' => $generator, 'revision' => 0, 'definition' => $definition, 'definitionHash' => DefinitionHasher::hash( $definition ), ), 'brandProfile' => null, 'sources' => array(), 'schemaVersion' => (int) ( $definition['schemaVersion'] ?? 1 ), 'rendererVersion' => Renderer::RENDERER_VERSION, ); $result = $this->snapshots->findOrCreate( 'definition', $generator, $payload, array( 'createdBy' => $user_id ) ); $this->snapshots->touch( $result['id'] ); return array( 'id' => $result['id'], 'hash' => $result['hash'], 'payload' => $payload ); } /** * Resolve a Blueprint's `sources.items` 'src:' refs to source * CONFIG only (never cached content/extracted text). * * @param array $definition Blueprint definition. * @return array */ private function sourcesForDefinition( array $definition ): array { $items = isset( $definition['sources']['items'] ) && is_array( $definition['sources']['items'] ) ? $definition['sources']['items'] : array(); $out = array(); foreach ( $items as $item ) { $ref = is_array( $item ) ? ( $item['ref'] ?? '' ) : ''; if ( ! is_string( $ref ) || 1 !== preg_match( '/^src:(\d+)$/', $ref, $match ) ) { continue; } $source = $this->sources->get( (int) $match[1] ); if ( null === $source ) { continue; } $out[] = array( 'id' => (int) $source['id'], 'name' => (string) $source['name'], 'kind' => (string) $source['kind'], 'url' => (string) $source['url'], 'urlField' => (string) $source['urlField'], 'scopeType' => (string) $source['scopeType'], 'scopeId' => (int) $source['scopeId'], 'staleAfterDays' => (int) $source['staleAfterDays'], ); } return $out; } /** * Resolve a 'run' payload's `definitionSnapshots` map to display-ready * {id,name,revision} entries, via a plain (non-touching) read of each * referenced definition snapshot. * * @param array $payload 'run' snapshot payload. * @return array */ private function blueprintEntriesFromPayload( array $payload ): array { $map = isset( $payload['definitionSnapshots'] ) && is_array( $payload['definitionSnapshots'] ) ? $payload['definitionSnapshots'] : array(); $entries = array(); foreach ( $map as $blueprint_id => $snapshot_id ) { $snapshot_row = $this->snapshots->get( (int) $snapshot_id ); if ( null === $snapshot_row ) { continue; } $blueprint = $snapshot_row['payload']['blueprint'] ?? array(); $entries[] = array( 'id' => (int) $blueprint_id, 'name' => (string) ( $blueprint['name'] ?? '' ), 'revision' => (int) ( $blueprint['revision'] ?? 0 ), ); } return $entries; } }