@acentric-cloud/kit

Pure snapshot helpers for framework agents: queues, source-order fanout, deterministic backoff, compaction continuations, recovery, log windows, keys and phases. Install with npm install @acentric-cloud/kit.

Every function is synchronous and deterministic in its arguments. Helpers return new values and do not mutate their inputs. Supply now from the agent's call. Invalid arguments throw KitError; reading below the loaded log window throws KitError('below_window').

queues.push and queues.drain manage an agent-owned snapshot queue. Supply a monotonic position from your snapshot when ordering inputs. Accepting an input is the step's answer; queued work in the snapshot is already accepted.

batch.start, batch.apply, batch.settle, batch.declarations and batch.results manage parallel calls. Store the whole batch in the snapshot: early outcomes live in done, and completed results are returned in source order. apply returns null for an unrelated or already settled key. A new batch needs a new tag because effect keys are single-use.

backoff uses attempt zero for the first retry. retry.next advances the attempt, returns a fresh @timer request with { at } args and its due time, and returns null when the policy is exhausted. retry.fired matches its successful timer outcome. retry.classify considers threw and timeout retryable; provider-specific retry decisions belong to the author.

compaction.begin stores a continuation, returned by finish on success, failure or interruption. Successful summaries append a compaction log entry. Use compaction.window from the agent's window(snapshot) function; store the compaction state directly or under snapshot.compaction. compaction.cut can keep call/result pairs together.

log.view, log.latest and log.since operate on the framework's { start, next, entries } log window. Entries carry numeric seq and at. keys and phases help express deterministic snapshot transitions. A user stop is an agent-defined input: drop pending requests to cancel them, or retain them with abort: true to receive their outcomes.

@acentric-cloud/kit/testing exports simulate, sweep, PureAgent and AgentFactory. A scenario supplies { config?, now, tick?, messages? } or an events script. Events deliver a message, crash, suspend, resume or upgrade to another pure agent. kinds supplies handler defaults for modes and crash budgets. Simulation never calls handlers: script their outcomes. Unknown kinds fail as ordinary effect messages, and due @timer requests produce { ok: null } automatically.

Traces contain steps and their accepted/rejected/failed answers, effect diffs, the full log, finalState, running effects and pending messages. Arguments are frozen copies. Rejected config messages keep the old config; accepted ones apply it to effects and view. Failed steps save nothing and remain pending until resume or upgrade. An upgrade delivers migrated before any queued message. Effects retain their original args, disappear without a result on cancellation, and never reuse finished or cancelled keys. A crash reruns reissue work with a higher attempt or interrupts once work. Voluntary stops do not spend the crash budget.

sweep(factory, scenario, { crashEvery }) rebuilds closure bindings at each sampled delivery boundary without rerunning init. It compares whole traces, reporting identical or differs; differences can be legitimate once interruptions and need an author-specific oracle. The simulator tests pure code and a scripted recovery model, not database leases, resource limits, real handlers or process scheduling.