Jidoka.Session.Data (Jidoka v0.9.0)

Serializable session envelope for running an agent across requests.

A session is data. It stores the agent spec, request history, hibernated snapshots, pending review requests, and the latest result/error. It does not own processes or runtime capabilities.

Summary

Types

status()

t()

Functions

bump_revision(session)

Increments the durable session revision.

clear_lease(session)

Removes active lease ownership from a session.

fork(source, snapshot, lineage, opts \\ [])

Builds a new session from a copied, safe snapshot and lineage data.

from_input(session)

Normalizes an existing session, keyword list, or map.

latest_snapshot(data)

Returns the most recent session snapshot, if one exists.

merge_snapshots(existing, additions)

Merges snapshot evidence without adding duplicate snapshot ids.

new(attrs)

Builds a durable session from keyword or map attributes.

new!(attrs)

Builds a durable session and raises if the attributes are invalid.

put_cancellation(session, cancellation)

Records typed cancellation evidence and marks the session as cancelled.

put_durable_checkpoint(session, snapshot)

Records a durable in-run checkpoint while lease ownership stays active.

put_error(session, reason)

Records a session error and marks the session as failed.

put_lease(session, lease)

Adds active lease ownership to a running session.

put_request(session, request)

Adds a request and marks the session as running.

put_result(session, result)

Adds a completed turn result and updates semantic agent state.

put_snapshot(session, snapshot)

Adds a snapshot and marks the session as hibernated.

schema()

Returns the Zoi schema for a durable session.

schema_version()

Returns the current durable session schema version.

start(spec, opts \\ [])

Starts durable session data for an agent specification.

statuses()

Returns the possible durable session statuses.

Types

status()

@type status() ::
  :new | :running | :hibernated | :waiting | :finished | :cancelled | :error

t()

@type t() :: %Jidoka.Session.Data{
  agent_id: binary(),
  error: nil | nil | any(),
  lease: nil | nil | term(),
  lineage: nil | nil | term(),
  metadata: map(),
  pending_reviews: [term()],
  requests: [term()],
  result: nil | nil | term(),
  revision: integer(),
  schema_version: integer(),
  session_id: binary(),
  snapshots: [term()],
  spec: term(),
  status:
    (((((:new | :running) | :hibernated) | :waiting) | :finished) | :cancelled)
    | :error
}

Functions

bump_revision(session)

@spec bump_revision(t()) :: t()

Increments the durable session revision.

clear_lease(session)

@spec clear_lease(t()) :: t()

Removes active lease ownership from a session.

fork(source, snapshot, lineage, opts \\ [])

@spec fork(t(), Jidoka.Snapshot.t(), Jidoka.Session.Lineage.t(), keyword()) ::
  {:ok, t()} | {:error, term()}

Builds a new session from a copied, safe snapshot and lineage data.

from_input(session)

@spec from_input(t() | keyword() | map()) :: {:ok, t()} | {:error, term()}

Normalizes an existing session, keyword list, or map.

latest_snapshot(data)

@spec latest_snapshot(t()) :: Jidoka.Snapshot.t() | nil

Returns the most recent session snapshot, if one exists.

merge_snapshots(existing, additions)

@spec merge_snapshots([Jidoka.Snapshot.t()], [Jidoka.Snapshot.t()]) :: [
  Jidoka.Snapshot.t()
]

Merges snapshot evidence without adding duplicate snapshot ids.

new(attrs)

@spec new(keyword() | map()) :: {:ok, t()} | {:error, term()}

Builds a durable session from keyword or map attributes.

new!(attrs)

@spec new!(keyword() | map()) :: t()

Builds a durable session and raises if the attributes are invalid.

put_cancellation(session, cancellation)

@spec put_cancellation(t(), Jidoka.Cancellation.t() | term()) :: t()

Records typed cancellation evidence and marks the session as cancelled.

put_durable_checkpoint(session, snapshot)

@spec put_durable_checkpoint(t(), Jidoka.Snapshot.t()) :: t()

Records a durable in-run checkpoint while lease ownership stays active.

put_error(session, reason)

@spec put_error(t(), term()) :: t()

Records a session error and marks the session as failed.

put_lease(session, lease)

@spec put_lease(t(), Jidoka.Session.Lease.t()) :: t()

Adds active lease ownership to a running session.

put_request(session, request)

@spec put_request(t(), Jidoka.Turn.Request.t()) :: t()

Adds a request and marks the session as running.

put_result(session, result)

@spec put_result(t(), Jidoka.Turn.Result.t()) :: t()

Adds a completed turn result and updates semantic agent state.

put_snapshot(session, snapshot)

@spec put_snapshot(t(), Jidoka.Snapshot.t()) :: t()

Adds a snapshot and marks the session as hibernated.

schema()

@spec schema() :: Zoi.schema()

Returns the Zoi schema for a durable session.

schema_version()

@spec schema_version() :: pos_integer()

Returns the current durable session schema version.

start(spec, opts \\ [])

@spec start(
  Jidoka.Agent.Spec.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Starts durable session data for an agent specification.

statuses()

@spec statuses() :: [status()]

Returns the possible durable session statuses.