Squidie.Runtime.Journal.Options (squidie v0.1.2)

Validates public options that reach journal-backed runtime threads.

Journal-backed start, inspection, and explanation all cross the same storage boundary: caller-provided storage config is normalized into a Squidie journal storage struct, and caller-provided run or queue identifiers become part of journal thread ids. This module keeps that validation in one place so those public APIs fail with structured, redacted errors before invalid values can reach an adapter or file-backed thread path.

The validation is intentionally about runtime safety, not compatibility. It accepts the current Jido storage adapter shape through a Squidie-owned boundary, validates the built-in adapters whose required options can otherwise raise, and keeps thread id components to a conservative portable character set.

Summary

Functions

queue(queue \\ "default")

Normalizes and validates a dispatch queue name for use in journal thread ids.

storage(storage)

Validates a journal storage config before a public API calls the adapter.

thread_part(value, field)

Validates a caller-provided journal thread-id component.

uuid(value)

Validates and canonicalizes a public run id that must be a UUID.

Functions

queue(queue \\ "default")

@spec queue(term()) ::
  {:ok, String.t()} | {:error, {:invalid_option, {:queue, :invalid}}}

Normalizes and validates a dispatch queue name for use in journal thread ids.

Atoms are converted to strings. Queue names must be non-empty and use the conservative portable thread-id character set enforced by this module.

storage(storage)

@spec storage(term()) ::
  {:ok, Squidie.Runtime.Journal.Storage.t()}
  | {:error, {:invalid_option, term()}}

Validates a journal storage config before a public API calls the adapter.

Invalid configs return structured, redacted option errors. Built-in adapters that raise for missing required options are checked here first. Treat journal_storage as trusted host configuration, not request-derived input.

thread_part(value, field)

@spec thread_part(term(), atom()) ::
  {:ok, String.t()} | {:error, {:invalid_option, term()}}

Validates a caller-provided journal thread-id component.

Use this for public identifiers, such as run ids in projection reads, that are

not required to be UUIDs but still become part of a Jido thread id.

uuid(value)

@spec uuid(term()) ::
  {:ok, String.t()} | {:error, {:invalid_option, {:run_id, :invalid}}}

Validates and canonicalizes a public run id that must be a UUID.

Journal starts use UUID run ids so caller-provided ids are safe as stable workflow thread identifiers and duplicate-start fences.