<?php
/**
 * Public, read-only integration contract. No customer data or vendor calls.
 *
 * @package AffStackDevImageManager
 */

namespace AffStackDev\ImageManager;

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

/**
 * Image Manager's descriptive contract for other plugins (the Suite, importers): what it provides and owns, announced
 * once after boot.
 */
final class Foundation {
	public const CONTRACT = '1.5'; // 1.5 (1.9.0): three descriptive fields are left out.
	/**
	 * Whether Image Manager has booted and announced its contract.
	 *
	 * @var bool
	 */
	private static bool $ready = false;

	/**
	 * Whether the booted contract is at least the version asked for.
	 *
	 * @param string $minimum The lowest contract version wanted, such as 1.0 or 1.2.0.
	 * @return bool True when booted and new enough.
	 */
	public static function available( string $minimum = '1.0' ): bool {
		if ( ! self::$ready || ! preg_match( '/^\d+\.\d+(?:\.\d+)?$/D', $minimum ) ) {
			return false;
		}
		$current = 1 === substr_count( self::CONTRACT, '.' ) ? self::CONTRACT . '.0' : self::CONTRACT;
		$minimum = 1 === substr_count( $minimum, '.' ) ? $minimum . '.0' : $minimum;
		return version_compare( $current, $minimum, '>=' );
	}
	/** Fires once after successful boot. Consumers cannot replace this descriptor. */
	public static function announce(): void {
		if ( self::$ready ) {
			return;
		}
		self::$ready = true;
		/**
		 * Fires once, after Image Manager has booted, with its descriptive contract.
		 *
		 * @since 1.7.0.4 Earliest release in the source history.
		 *
		 * @param array $contract The stable contract descriptor (Foundation::contract()); consumers cannot replace it.
		 */
		// The contract reads constants of many modules (Backup, Batch, Workflow...), so it is built only when a callback
		// listens: a request without one compiles none of them (F-DEMO-01). did_action() counts the boot either way.
		do_action( 'afsd_im_ready', has_action( 'afsd_im_ready' ) || has_action( 'all' ) ? self::contract() : array() );
	}
	/**
	 * Stable descriptive contract, not a backup, a file mutation API, or an encoder self-test.
	 * No settings, source URLs, server paths, filenames, keys, or user records are returned.
	 */
	public static function delivery_contract(): array {
		return array(
			'version'                  => 1,
			'render_function'          => 'affstackdev_image_manager_render_image_html',
			'render_function_purpose'  => 'Render an already-generated native attachment img fragment through the current supported delivery policy; no conversion or setting mutation occurs.',
			'integration_matrix'       => Integrations::matrix(),
			'theme_layout_owner'       => 'theme_or_rendering_component',
			'derivative_owner'         => 'affstackdev-image-manager',
			'unknown_surface_behavior' => 'native_fallback',
			'browser_verification_required_for_download_proof' => true,
		);
	}

	/**
	 * The descriptive contract: versions, what needs no account, the data Image Manager owns and the boundaries it keeps.
	 *
	 * @return array The contract.
	 */
	public static function contract(): array {
		return array(
			'contract'                  => 'affstackdev-image-manager',
			'contract_version'          => self::CONTRACT,
			'plugin_version'            => VERSION,
			'account_required'          => false,
			'suite_required'            => false,
			'runtime_ready'             => self::$ready,
			'suite_product_id'          => Suite::ID,
			'database_schema'           => SCHEMA,
			'record_contract_version'   => 1,
			'progress_contract_version' => 1,
			'delivery_contract_version' => 1,
			'features'                  => array(
				'compression_modes'                => array( 'lossless', 'high', 'maximum' ),
				'conditional_output_formats'       => array( 'image/jpeg', 'image/png', 'image/webp', 'image/avif' ),
				'bulk_actions'                     => Batch::ACTIONS,
				'controlled_display_sizes'         => true,
				'comparisons'                      => true,
				'public_html_check'                => true,
				'signed_in_browser_check'          => true,
				'supported_render_api'             => true,
				'php_workflow'                     => true,
				'local_processing'                 => true,
				'automatic_public_page_rechecks'   => 'optional_known_pages',
				'pdf_page_conversion'              => 'local_host_capability_new_attachment',
				'folder_upload'                    => 'native_wordpress_up_to_eight_files',
				'folder_drag_drop'                 => 'review_before_apply',
				'image_replacement'                => 'same_attachment_id_new_file_url',
				'replacement_undo'                 => 'latest_revision_verified_old_files',
				'woocommerce_variation_delivery'   => 'classic_gallery_coordinated_native_fallback',
				'media_folders'                    => true,
				'media_collections'                => true,
				'media_library_views'              => array( 'grid', 'list' ),
				'native_media_details_integration' => true,
				'basic_editor'                     => true,
				'editor_mode'                      => 'copy_first_non_destructive',
				'portable_media_export'            => true,
				'local_media_snapshots'            => true,
				'local_device_download'            => true,
				'selective_media_restore'          => true,
				'portable_backup_format'           => Backup::FORMAT . '/v' . Backup::FORMAT_VERSION,
				'password_encrypted_zip'           => 'host_capability',
				'cloud_backup'                     => true,
				'cloud_backup_providers'           => array( 'google_drive', 's3_compatible' ),
				'scheduled_remote_backup'          => true,
				'release_health_report'            => true,
			),
			'ownership'                 => array(
				'wordpress'     => array( 'attachments', 'originals', 'native_metadata', 'native_sizes', 'content_and_product_relationships' ),
				'image_manager' => array( 'source_index', 'observed_usage', 'recipes', 'manifests', 'managed_copies', 'batch_selection', 'job_coordination', 'virtual_media_folders', 'virtual_media_collections', 'edit_drafts', 'edit_lineage', 'portable_backup_index', 'private_local_snapshots', 'remote_backup_index', 'remote_transfer_state', 'encrypted_remote_credentials' ),
			),
			'records'                   => array(
				'source'              => array(
					'identity'     => array( 'source_key', 'attachment_id', 'revision' ),
					'table_suffix' => 'afsd_im_sources',
					'id_scope'     => 'site_local_not_portable',
				),
				'manifest'            => array(
					'location' => 'source.manifest',
					'fields'   => array( 'schema', 'revision', 'recipe', 'variants', 'responsive', 'draft', 'retired' ),
					'owner'    => 'image_manager',
				),
				'usage'               => array(
					'table_suffix' => 'afsd_im_owners',
					'certainty'    => 'observed_not_exhaustive',
				),
				'batch'               => array(
					'table_suffix' => 'afsd_im_batch',
					'identity'     => array( 'batch_id', 'source_id' ),
					'states'       => array( 'waiting', 'working', 'checking', 'complete', 'review', 'skipped', 'failed' ),
				),
				'workflow'            => array(
					'option'                               => Workflow::OPTION,
					'identity'                             => 'id',
					'preserve_active_or_paused_on_upgrade' => true,
				),
				'progress'            => array(
					'option'  => Progress::OPTION,
					'purpose' => 'last_durable_checkpoint_not_download_evidence',
				),
				'automatic_discovery' => array(
					'option'                => Auto_Discovery::OPTION,
					'notice_option'         => Auto_Discovery::NOTICE,
					'owner'                 => 'image_manager',
					'maximum_pending_pages' => Auto_Discovery::LIMIT,
					'autoload'              => false,
					'portable_media_data'   => false,
				),
			),
			'safety'                    => array(
				'originals_overwritten_by_optimization' => false,
				'automatic_quality_change_on_upgrade'   => false,
				'public_delivery_requires_eligibility'  => true,
				'generated_files_retained_on_uninstall' => true,
				'no_frontend_conversion'                => true,
			),
			'hooks'                     => array(
				'afsd_im_ready' => array(
					'arguments' => array( 'contract' ),
					'frequency' => 'once_per_successful_boot',
					'authority' => 'notification_only',
				),
			),
			'delivery'                  => self::delivery_contract(),
			'export'                    => array(
				'implemented'         => true,
				'namespace'           => Backup::FORMAT,
				'format_version'      => Backup::FORMAT_VERSION,
				'profiles'            => array( 'essential', 'published' ),
				'cloud_backup'        => true,
				'remote_providers'    => array( 'google_drive', 's3_compatible' ),
				'local_download'      => true,
				'required_properties' => array( 'documented_manifest', 'standard_media_files', 'restore_without_account', 'no_credentials', 'explicit_site_id_mapping', 'checksums', 'selective_restore' ),
			),
		);
	}
}