reflexr.workspace¶

Return a workspace's rules: the code rules, then its active stored rules, by name.

Everything that needs a workspace's rules finds them here, and nothing is cached. Without stored_rules there are only the code rules, and nothing to read; with it, only stored rules in its namespaces, so a namespace a deploy dropped is hidden.

Parameters:

Return a handle on a tenant's workspace, acting as actor.

This is the only place a tenant id enters; nothing on the handle can reach another tenant. The surfaces pass their authorize hook, so each refuses a workspace alike.

Raises:

Carry out a command the way every surface should, once per command_id.

The command is carried out through the handle, as its actor. A rejection is the result, not raised.

A command is known by its tenant, workspace, sender (the handle's actor, as a participant) and command_id. The first time, it is carried out and its result is remembered. A repeated id returns the remembered result and carries nothing out, whatever command it comes with, so a retry is safe on every surface.

Return the schedules that tick in a tenant's workspaces, as the tenant may see them.

A schedule that targets particular workspaces lists only the tenant's own, so no tenant sees another's ids; one that targets none of them is left out.

Return a handle on the same workspace that acts as actor.

Return a handle whose events a run caused, in that run's causal chain.

The reactor gives each run such a handle, so the events its action emits record the firing and run behind them and count towards the chain's depth.

Publish an event into the workspace's log.

Parameters:

Raises:

Publish events atomically and in order: all of them are logged, or none.

Parameters:

Raises:

Record feedback on a run, a firing or a whole causal chain.

The feedback joins the causal chain of what it is about, so it appears in that chain's session.

Raises:

Make a run runnable now.

A dead-lettered, cancelled or skipped run gets a fresh retry budget; a run waiting to retry stops waiting.

Raises:

Give up on a waiting or dead-lettered run, unblocking later runs of its scope.

Raises:

Cancel a run that has not finished. A running attempt's result is discarded.

Raises:

Save a running run's progress after a step, and append reflexr:run_progressed.

Actions call this through Reaction.checkpoint, so a retry resumes after the last step.

Parameters:

Raises:

Reset a rule to evaluate the log again from after from_seq.

Parameters:

Returns:

Raises:

Install a stored rule: its first version, or the next version of an archived one.

The rule starts at its reflexr:rule_installed fact, so it acts on what is logged after it. A rule installed again is reset there, continuing its generation, so no firing id repeats.

Parameters:

Returns:

Raises:

Replace an active stored rule with a new version.

A new condition or scope resets the rule at its reflexr:rule_installed fact, as a changed code rule is reset; any other change keeps its state.

Parameters:

Returns:

Raises:

Archive a stored rule, and cancel its unfinished runs.

Its scope states are cleared and its progress kept, so a rule installed again under its name continues its generation. The runs' reflexr:run_cancelled facts follow the reflexr:rule_archived fact, in the same transaction.

Parameters:

Returns:

Raises:

Return the seq of the latest envelope, or 0 if the log is empty.

Return envelopes in the window after_seq < seq < before_seq, in order.

Parameters:

Raises:

Yield envelopes after after_seq, then each new one as it is logged.

Reading the log is untraced, so a subscription that polls storage makes no trace per poll (ADR-0040); what the subscriber does with each envelope is traced as usual.

Return how far a named consumer of the log has got: the seq it saved, or 0.

A consumer, such as a feedback mirror, saves its cursor with save_cursor and carries on after it when it starts again.

Save how far a named consumer of the log has got: it is done with seq.

A cursor only moves forward: saving a seq below the saved one leaves it, so a consumer that runs in several processes, each at its own pace, cannot move it back.

Return a run.

Raises:

Return runs, newest first, optionally of one rule, status or scope.

Return the envelopes rules could not evaluate, oldest first.

Return when each schedule last ticked in this workspace.

Return each rule's progress: its cursor, generation and pending deadlines.

Return one of the workspace's rules, with a stored rule's version and provenance.

Raises:

Return the status of each of the workspace's rules, code rules first.

Every surface reports this, so they agree. A rule that has not evaluated the workspace yet is at cursor 0, and the progress of a rule the workspace no longer has, such as a code rule no longer registered or an archived stored rule, is left out.

Return when each schedule that targets this workspace last ticked and ticks next.

Every surface reports this, so they agree. A schedule that has not checked the workspace yet has neither.

Attempt the runs that are due and can start, up to limit of them.

Returns:

Evaluate and execute until nothing more happens now.

Useful in tests and scripts. Runs waiting to retry later are left waiting. A round in which another reactor held a lease this one needed, on a workspace to evaluate or a run to attempt, is not idle, since the other may be about to let that work go: the reactor waits a few milliseconds, longer each time up to a tenth of a second, and tries again.

Raises:

Tick, evaluate and execute until stopped, checking for work every poll_interval.

A pass that fails, as when the database is briefly unreachable, is logged and the next one tries again: leases and transactions leave nothing half done.

Setting stop stops the reactor gracefully. Evaluation stops after its current batch, and attempts still waiting for a place do not start. Running attempts have grace to end; then their actions are cancelled, and each attempt is recorded as abandoned, a failed attempt that is retried under the rule's policy. Once every lease it held is released, serve returns. Without stop, it runs until cancelled.

Parameters:

Publish the ticks that are due, for every schedule and the workspaces it targets.

A schedule's first check in a workspace starts its timetable there; its first tick comes at its next time after that.

Returns:

Evaluate every enabled rule over new envelopes until each is caught up with the log.

Parameters:

Returns:

Return the params as model, the action's params model.

An agent's tools and prompt, and a graph's steps, read their params this way; a function given to with_params gets them as its second argument.

Raises:

Save the run's progress after step, so a retry resumes after it.

The saved state is reaction.run.checkpoint on the next attempt.

Raises:

Publish an event caused by this run.

Its id is derived from the run, its last checkpoint, and how many events it emitted since, so a retried attempt that emits the same events again adds nothing to the log, and a graph resumed after a checkpoint never reuses an earlier event's id.

Raises:

Return the result remembered for a command, if there is one.

Remember a command's result.

Return the result remembered for a command, if it is still remembered.

Remember a command's result, forgetting the oldest beyond the capacity.

Yield the schedule's times strictly after moment, in order.

Return the ticks due after last and by now, as catch_up allows.

Whether the schedule ticks in a workspace.

Begin a transaction: it commits if the block exits normally, and rolls back if not.

Return the log's latest seq, or 0 if it is empty.

Return logged envelopes in the window after_seq < seq < before_seq, in order.

Parameters:

Callers give at most one of limit and last, and no negative numbers; read checks.

Yield envelopes after after_seq: the stored ones, then each one as it commits.

Return a run, or None.

Return runs, newest first, optionally filtered.

Return the envelopes rules could not evaluate, oldest first.

Return every rule's progress in a workspace.

Return the time of each schedule's last tick in a workspace.

Return a workspace's active stored rules, by name, in code-point order.

Return every workspace with a log, for the reactor to evaluate.

Return the runs to attempt now, across workspaces, oldest first.

These are the pending and retrying runs due by now that can start, and running runs whose run_lease has lapsed, because their executor stopped. A pending or retrying run of an ordered rule can start only if no earlier run of its scope, in firing order (fired_seq, then creation), holds the scope, so a scope's backlog yields one run however deep it is. Runs of the disabled rules are left out. So neither the runs waiting behind others nor those of disabled rules take up the limit.

Take or renew an exclusive lease. Return False if another holder has it.

Release a lease if holder has it.

Return how far a named consumer of the log has got: the seq saved, or 0.

Save how far a named consumer of the log has got, such as a feedback mirror.

A cursor only moves forward: saving a seq below the saved one leaves it, so a consumer running in several processes cannot move it back.

Append events to the log, assigning each the next seq and a ts.

ts is the later of the clock and the previous envelope's ts, so it never decreases within a workspace. Callers make publishing idempotent by looking an id up with envelope first; appending an id that is already in the log, or earlier in the same transaction, raises ValueError.

Return the envelope of an event id, or None.

Return the log's latest seq, or 0 if it is empty.

Return up to limit envelopes after after_seq, in order.

Return a rule's progress in this workspace, or None if it has none yet.

Save a rule's progress.

Return the stored state of the given scopes of a rule; missing scopes are left out.

Save the state of scopes of a rule.

Delete every scope state of a rule, when it is reset.

Return a run, or None.

Insert or update runs.

Return every run of a rule's scope that has not succeeded, in firing order.

Record envelopes a rule could not evaluate.

Return the time of a schedule's last tick in this workspace, or None.

Save the time of a schedule's last tick.

Return a stored rule, active or archived, or None if no rule of that name is stored.

Return the workspace's active stored rules, by name, in code-point order.

Save a stored rule's next version, which archives it if its status is archived.

Versions are numbered from 1 per name, so callers check an expected version by reading stored_rule first; saving any version but the next raises ValueError.

Describe the given rules.

Whether a run holds back the later runs of its scope (holds).

Begin a transaction; it holds the workspace's lock until it ends.

Return the log's latest seq, or 0 if it is empty.

Return logged envelopes in the window after_seq < seq < before_seq, in order.

Of those of types, if given: the first limit or the last last.

Yield stored envelopes after after_seq, then each new one as it commits.

Return a run, or None.

Return runs, newest first, optionally filtered.

Return the envelopes rules could not evaluate, oldest first.

Return every rule's progress in a workspace.

Return the time of each schedule's last tick in a workspace.

Return a workspace's active stored rules, by name, in code-point order.

Return every workspace with a log.

Return the runs to attempt now that can start, across workspaces, oldest first.