Spaces:
Sleeping
Sleeping
File size: 2,721 Bytes
f51c224 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | <?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;
}
|