<?php

declare(strict_types=1);

namespace Drupal\flowdrop_memory\Entity;

use Drupal\Core\Entity\ContentEntityInterface;

/**
 * Interface for FlowDrop memory record entities.
 *
 * A memory record holds a single scoped key-value pair with optional expiry.
 *
 * @api
 */
interface MemoryRecordInterface extends ContentEntityInterface {

  /**
   * Returns the memory scope.
   *
   * @return string
   *   The scope string (e.g. "pipeline", "session", "global").
   */
  public function getScope(): string;

  /**
   * Returns the scope identifier.
   *
   * @return string
   *   The scope ID, or empty string for no sub-scope.
   */
  public function getScopeId(): string;

  /**
   * Returns the memory key.
   *
   * @return string
   *   The key name.
   */
  public function getMemoryKey(): string;

  /**
   * Returns the stored value (JSON-decoded).
   *
   * @return mixed
   *   The decoded value.
   */
  public function getValue(): mixed;

  /**
   * Sets the stored value (JSON-encodes before persisting).
   *
   * @param mixed $value
   *   The value to store. Must be JSON-serializable.
   *
   * @return static
   */
  public function setValue(mixed $value): static;

  /**
   * Returns the expiry timestamp.
   *
   * @return int|null
   *   Unix timestamp, or NULL if the record never expires.
   */
  public function getExpiry(): ?int;

  /**
   * Sets the expiry timestamp.
   *
   * @param int|null $timestamp
   *   Unix timestamp, or NULL to make the record permanent.
   *
   * @return static
   */
  public function setExpiry(?int $timestamp): static;

  /**
   * Checks whether this record has expired.
   *
   * @return bool
   *   TRUE if the expiry is set and in the past.
   */
  public function isExpired(): bool;

}
