sa-orchestration/includes/interface-sa-surface-adapter.php

<?php
defined( 'ABSPATH' ) || exit;

/**
 * Surface adapter contract.
 *
 * Asterion binds to surface adapters, not tables. External schema
 * assumptions are bounded to adapter implementations; consumers of
 * the contract (the orchestration layer) only see the contract.
 *
 * Each surface (fluent-support, fluent-boards, fluentcrm, derived,
 * future) has — or will have — a concrete implementation of this
 * interface. The implementation encapsulates all schema-specific
 * resolution. If the external surface's schema changes, the change
 * lands in one file (the adapter), not across every caller.
 *
 * Contract guarantees:
 *   - id():        the surface identifier this adapter handles
 *   - validate():  is this ref shape-correct AND resolvable?
 *   - resolve():   the underlying surface row, or null
 *   - label():     a human-readable label for the row
 *   - hydrate():   structured snapshot for downstream consumption (Sara, etc.)
 *
 * Out-of-scope for this interface:
 *   - mutation of surface state (orchestration must not mutate Fluent)
 *   - paginated listing (a separate adapter capability if needed)
 */
interface SA_Orch_Surface_Adapter {

    /** Surface identifier (e.g. 'fluent-boards', 'fluent-support'). */
    public function id(): string;

    /**
     * Is the ref shape-correct AND resolvable to a real row under this surface?
     * Returns true only if both conditions hold. Pure read; no side effects.
     */
    public function validate( string $ref ): bool;

    /**
     * Resolve the ref to the underlying surface row, or null if missing.
     * The shape of the returned object is implementation-defined; consumers
     * should access fields only through the adapter's other methods (label,
     * hydrate) rather than touching schema directly.
     */
    public function resolve( string $ref );

    /** Human-readable label for the row, falling back to the ref if unresolvable. */
    public function label( string $ref ): string;

    /**
     * Structured snapshot of the bound object — title, state, description
     * summary, recent activity, etc. — shaped for downstream consumers (Sara).
     * Returns null if the ref does not resolve. The implementation decides
     * which fields are meaningful for its surface; consumers should treat
     * any field as optional and tolerate missing/empty values.
     *
     * Conventional keys (all optional): ref, title, status, stage, priority,
     * board_name, customer, description, recent_activity (array of items;
     * each item has at minimum { created_at, excerpt } and may also include
     * optional 'by' for the author of the activity).
     */
    public function hydrate( string $ref ): ?array;
}