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

Immutable persistence boundary for canonical Definitions and Manifest V2.

Adapters store one opaque canonical artifact per Definition.Ref. Core owns artifact encoding, publication receipts, integrity verification, parent checks, and idempotency read-back. An adapter must never replace different bytes under an existing key.

A configured Spectre.Instance.CheckpointStore is a durable boundary. Such a runtime may use only a Definition Store whose durability/1 returns :durable; the bundled in-memory store is intentionally :volatile.

Summary

Types

artifact()

config()

durability()

receipt()

Callbacks

durability(keyword)

get(t, keyword)

identity(keyword)

put(t, binary, keyword)

Functions

artifact_schema_version()

Returns the publication artifact schema version.

candidate_artifact_schema_version()

Returns the immutable Candidate artifact schema version.

durability(store)

Returns the adapter's declared durability after validating its callbacks.

fetch(store, ref, opts \\ [])

Fetches and fully verifies one published artifact.

fetch_candidate(store, ref, opts \\ [])

Re-reads and verifies a Candidate, its bound Definition, and governance receipts.

fetch_gate_receipt(store, ref, opts \\ [])

Re-reads and verifies a governance gate receipt by content Ref.

gate_receipt_artifact_schema_version()

Returns the immutable gate-receipt artifact schema version.

identity(store)

Returns the portable logical identity of the configured Store.

normalize(module)

Normalizes a Store module or {module, opts} configuration.

publish(store, canonical, manifest, opts \\ [])

Atomically publishes Definition bytes, Manifest bytes, and a core receipt.

publish_candidate(store, candidate, opts \\ [])

Publishes one immutable bootstrap or governed Candidate after re-reading its Definition.

publish_gate_receipt(store, receipt, opts \\ [])

Publishes one immutable governance gate receipt.

receipt_schema_version()

Returns the publication receipt schema version.

validate_durability_pair(checkpoint_store, definition_store)

Rejects a durable Checkpoint Store paired with a volatile Definition Store.

Types

artifact()

@type artifact() :: %{
  definition: Spectre.Definition.Canonical.t(),
  manifest: Spectre.Definition.Manifest.t(),
  receipt: receipt()
}

config()

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

durability()

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

receipt()

@type receipt() :: %{
  schema_version: pos_integer(),
  publication_id: String.t(),
  definition_ref: String.t(),
  manifest_digest: String.t(),
  store_id: term(),
  durability: durability()
}

Callbacks

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()

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 publication artifact schema version.

candidate_artifact_schema_version()

@spec candidate_artifact_schema_version() :: pos_integer()

Returns the immutable Candidate artifact schema version.

durability(store)

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

Returns the adapter's declared durability after validating its callbacks.

fetch(store, ref, opts \\ [])

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

Fetches and fully verifies one published artifact.

Verification covers the lookup key, canonical Definition Ref, Manifest digest/binding, publication receipt, and current component registry.

fetch_candidate(store, ref, opts \\ [])

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

Re-reads and verifies a Candidate, its bound Definition, and governance receipts.

Supplying an in-memory Candidate struct is never an activation authority; callers must pass the returned Ref to this function or to Spectre.Instance.activate/3.

fetch_gate_receipt(store, ref, opts \\ [])

@spec fetch_gate_receipt(
  config(),
  Spectre.Gate.Receipt.Ref.t() | String.t(),
  keyword()
) ::
  :not_found | {:ok, Spectre.Gate.Receipt.t()} | {:error, term()}

Re-reads and verifies a governance gate receipt by content Ref.

gate_receipt_artifact_schema_version()

@spec gate_receipt_artifact_schema_version() :: pos_integer()

Returns the immutable gate-receipt artifact schema version.

identity(store)

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

Returns the portable logical identity of the configured Store.

normalize(module)

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

Normalizes a Store module or {module, opts} configuration.

publish(store, canonical, manifest, opts \\ [])

@spec publish(
  config(),
  Spectre.Definition.Canonical.t(),
  Spectre.Definition.Manifest.t(),
  keyword()
) ::
  {:ok, receipt()} | {:error, term()}

Atomically publishes Definition bytes, Manifest bytes, and a core receipt.

Parent Definitions must already resolve. A successful adapter write is read back and compared byte-for-byte before the publication receipt is returned. Publishing the same artifact twice is idempotent; different bytes under the same Ref are an immutable conflict.

publish_candidate(store, candidate, opts \\ [])

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

Publishes one immutable bootstrap or governed Candidate after re-reading its Definition.

The Candidate is stored under its content-addressed Candidate.Ref. Its Manifest digest and publication id must match the verified Definition artifact already present in the same trusted Store.

publish_gate_receipt(store, receipt, opts \\ [])

@spec publish_gate_receipt(config(), Spectre.Gate.Receipt.t(), keyword()) ::
  {:ok, Spectre.Gate.Receipt.Ref.t()} | {:error, term()}

Publishes one immutable governance gate receipt.

receipt_schema_version()

@spec receipt_schema_version() :: pos_integer()

Returns the publication receipt schema version.

validate_durability_pair(checkpoint_store, definition_store)

@spec validate_durability_pair(Spectre.Instance.CheckpointStore.config(), config()) ::
  :ok | {:error, term()}

Rejects a durable Checkpoint Store paired with a volatile Definition Store.