Spectre.Experience.Store behaviour (Spectre v0.3.0)

Opt-in persistence boundary for redacted Experience evidence.

Unlike the Definition Store, this Store is not canonical Agent state and is never consulted for authorization or continuation ownership. Core verifies every content-addressed entry before exposing it to Reflection.

Summary

Types

config()

durability()

snapshot()

Callbacks

delete(t, keyword)

durability(keyword)

get(t, keyword)

identity(keyword)

list(keyword)

put(t, binary, keyword)

Functions

artifact_schema_version()

Returns the Experience Store artifact schema version.

decode_snapshot(encoded)

Decodes and verifies canonical snapshot bytes.

durability(store)

Returns the Store's declared durability.

empty_snapshot(definition_ref, as_of)

Builds an explicitly empty snapshot when Experience is not configured.

encode_snapshot(snapshot)

Encodes a snapshot with the production canonical codec.

fetch(store, ref)

Fetches and revalidates evidence by content Ref.

identity(store)

Returns the Store identity after validating its adapter callbacks.

list_evidence(store, definition_ref, opts \\ [])

Lists verified evidence for one Definition under an explicit time snapshot.

normalize(module)

Normalizes an Experience Store configuration.

publish(store, evidence)

Publishes immutable, content-addressed evidence and reads it back.

purge_expired(store, now, opts \\ [])

Deletes only expired, non-retained Experience evidence after explicit confirmation.

snapshot(store, definition_ref, opts \\ [])

Builds the exact redacted evidence snapshot bound by Reflection and Forge.

snapshot_from_data(data)

Restores and fully verifies a snapshot from portable data.

snapshot_to_data(snapshot)

Returns portable JSON-shaped snapshot data.

verify_snapshot(arg1)

Revalidates a snapshot and every embedded evidence item.

Types

config()

@type config() :: module() | {module(), keyword()}

durability()

@type durability() :: :volatile | :durable

snapshot()

@type snapshot() :: %{
  definition_ref: Spectre.Definition.Ref.t(),
  as_of: non_neg_integer(),
  evidence: [Spectre.Experience.Evidence.t()],
  evidence_refs: [String.t()],
  digest: String.t()
}

Callbacks

delete(t, keyword)

@callback delete(
  String.t(),
  keyword()
) :: :ok | :not_found | {:error, term()}

durability(keyword)

@callback durability(keyword()) :: durability()

get(t, keyword)

@callback get(
  String.t(),
  keyword()
) :: :not_found | {:ok, binary()} | {:error, term()}

identity(keyword)

@callback identity(keyword()) :: term()

list(keyword)

@callback list(keyword()) :: {:ok, [{String.t(), binary()}]} | {:error, term()}

put(t, binary, keyword)

@callback put(String.t(), binary(), keyword()) ::
  :ok | {:ok, :created | :existing} | {:error, term()}

Functions

artifact_schema_version()

@spec artifact_schema_version() :: pos_integer()

Returns the Experience Store artifact schema version.

decode_snapshot(encoded)

@spec decode_snapshot(binary()) :: {:ok, snapshot()} | {:error, term()}

Decodes and verifies canonical snapshot bytes.

durability(store)

@spec durability(config()) :: {:ok, durability()} | {:error, term()}

Returns the Store's declared durability.

empty_snapshot(definition_ref, as_of)

@spec empty_snapshot(Spectre.Definition.Ref.t() | String.t(), non_neg_integer()) ::
  {:ok, snapshot()} | {:error, term()}

Builds an explicitly empty snapshot when Experience is not configured.

encode_snapshot(snapshot)

@spec encode_snapshot(snapshot()) :: {:ok, binary()} | {:error, term()}

Encodes a snapshot with the production canonical codec.

fetch(store, ref)

@spec fetch(config(), Spectre.Experience.Evidence.Ref.t() | String.t()) ::
  :not_found | {:ok, Spectre.Experience.Evidence.t()} | {:error, term()}

Fetches and revalidates evidence by content Ref.

identity(store)

@spec identity(config()) :: {:ok, term()} | {:error, term()}

Returns the Store identity after validating its adapter callbacks.

list_evidence(store, definition_ref, opts \\ [])

@spec list_evidence(config(), Spectre.Definition.Ref.t() | String.t(), keyword()) ::
  {:ok, [Spectre.Experience.Evidence.t()]} | {:error, term()}

Lists verified evidence for one Definition under an explicit time snapshot.

normalize(module)

@spec normalize(config()) :: {:ok, {module(), keyword()}} | {:error, term()}

Normalizes an Experience Store configuration.

publish(store, evidence)

@spec publish(config(), Spectre.Experience.Evidence.t()) ::
  {:ok, Spectre.Experience.Evidence.Ref.t()} | {:error, term()}

Publishes immutable, content-addressed evidence and reads it back.

purge_expired(store, now, opts \\ [])

@spec purge_expired(config(), non_neg_integer(), keyword()) ::
  {:ok, [String.t()]} | {:error, term()}

Deletes only expired, non-retained Experience evidence after explicit confirmation.

snapshot(store, definition_ref, opts \\ [])

@spec snapshot(config(), Spectre.Definition.Ref.t() | String.t(), keyword()) ::
  {:ok, snapshot()} | {:error, term()}

Builds the exact redacted evidence snapshot bound by Reflection and Forge.

snapshot_from_data(data)

@spec snapshot_from_data(map()) :: {:ok, snapshot()} | {:error, term()}

Restores and fully verifies a snapshot from portable data.

snapshot_to_data(snapshot)

@spec snapshot_to_data(snapshot()) :: {:ok, map()} | {:error, term()}

Returns portable JSON-shaped snapshot data.

verify_snapshot(arg1)

@spec verify_snapshot(snapshot()) :: :ok | {:error, term()}

Revalidates a snapshot and every embedded evidence item.