<?php

/**
 * Contract each built-artifact type implements to plug into the shared backbone.
 *
 * @package LolaCore\Builder\Artifact
 * @license GPL-2.0-or-later
 */

declare(strict_types=1);

namespace LolaCore\Builder\Artifact;

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

/**
 * Adapter between an artifact library CPT and the shared builder backbone.
 *
 * The gate, installer, and blueprint builder read artifact state through this
 * interface instead of hardcoding a post type's meta keys, so a new artifact
 * kind (e.g. built blocks) only has to supply an adapter.
 */
interface ArtifactAdapter {

	/**
	 * Library post type storing this artifact kind (e.g. lolacore_plugin).
	 */
	public function postType(): string;

	/**
	 * Meta-key prefix for this artifact kind (e.g. '_lc_pb_').
	 *
	 * The attestation gate derives its meta keys and load-safe transient names
	 * from this prefix, so it MUST stay stable per artifact kind forever: live
	 * libraries carry these keys.
	 */
	public function metaPrefix(): string;

	/**
	 * Current library version of the artifact (>= 1).
	 */
	public function currentVersion( int $postId ): int;

	/**
	 * Artifact slug, or '' when missing.
	 */
	public function slug( int $postId ): string;

	/**
	 * Declared wp.org dependency slugs as stored (unnormalized).
	 *
	 * @return array<int, mixed>
	 */
	public function dependencies( int $postId ): array;

	/**
	 * Disk-bound file tree for the artifact (what an install would write).
	 *
	 * @throws \Exception When the artifact is incomplete (e.g. missing slug).
	 */
	public function filesMap( int $postId ): FilesMap;

	/**
	 * Main PHP blob exactly as persisted in the library.
	 *
	 * The load-safe cache hashes this raw value, so its semantics must not
	 * change per artifact kind once shipped (cache identity).
	 */
	public function storedPhp( int $postId ): string;

	/**
	 * Main PHP blob as it would load from disk (normalizers applied).
	 *
	 * FS-S2 seam: runtime validation is single-blob today; multi-file support
	 * lands with the block builder and will widen this contract deliberately.
	 */
	public function runtimePhp( int $postId ): string;
}
