The store slot's methods

Part of the adapter protocol, version 2 (an addition within it; no version of its own).

A store module keeps a host's run state: runs, parks, joins, waits and the arrivals they read, leases, the work queue, library sources, pull cursors and event receipts. listen-fire ships two (@lf/sqlite-store, the default, and @lf/postgres-store). A third-party one is a module listen-fire starts, or reaches at its URL, and calls over adapter protocol 2's HTTP, as it calls any module.

Installing one #

A folder in the project's externals folder, with an lf-external.yaml:

name: acme_store
kind: core
slot: store
command: [node, store.mjs]      # started in this folder; or `url:` for a remote one
settings:                       # optional; prompted by `listen-fire connect acme_store`
  - { name: path, label: the state file, secret: false, optional: false }
env: { LOG_LEVEL: info }        # optional

• lf.yaml names it for the slot: core: { store: acme_store }.
• listen-fire connect acme_store asks its settings, keeps them on its install entry in the secrets file, and opens it once (so a module that sets itself up, a schema say, does so then).
• Every slot takes such a module (the transport): the models, judge, files and browser slots' methods are models-slot.md, judge-slot.md, files-slot.md and browser-slot.md.

The envelope #

The adapter protocol's (the envelope, the transport): one POST per method, the method in the body, the install's settings in settings on every request.

• A runner's requests carry hostRelease, the release of the listen-fire that sent it ("0.15.2"; adapter protocol 2.8). A request without it did not state its sender's release: it comes from a runner before 0.15.2, or from a host that does not set it. A module serving runners of several releases answers each by its line: the methods it answers, and the meaning of those whose meaning changed under one name (see Changes). The movements and secrets slots share this envelope, so their requests carry it too.
• A method's params is one object, keyed in camel case. Its result is the answer; null for a method that answers nothing.
• An absent optional string is null.
• Instants are Date.toISOString strings; ids and tokens are strings the module mints.
• A failure is ok: false with an error. The code run_lease_lost, with data: { runId }, means a fenced write found the run's lease gone: listen-fire treats it as losing the run. Any other code is a store failure.
• listen-fire calls a store one method at a time and waits for each answer.
• A write that must not be torn by a crash is one method, which the store keeps as one transaction: all of it or none (parks.commit, parks.commitSegment, events.startRun, inbound.keepDelivery and waits.log). A remote store cannot hold a transaction open across requests, so there is no method that opens one.
• inbound.keepDelivery is also where a redelivery is kept out: its receipt is written first, unique on the subscription and the provider's delivery id, so a second delivery under that id, even one arriving while the first's work is still queued, writes nothing and answers kept: false.

Methods #

The first request is always store.open. The others are the run host's store families (RunHostStore in packages/movement-engine/services/run_host/), method for method. Their meaning is the contract suite's: undefined holds every store to the same cases, and apps/cli runs it through a store module (run_host_contract.test.ts).

The rows:

type RunRow = {
  id: string; file: string; movement: string; status: string; startedAt: string; finishedAt?: string | null;
  input: string; outcome: string | null; deliveryId: string | null;
  attempt?: number;      // the latest attempt's number; absent: 1
  attempts?: { attempt: number; status: string; startedAt: string; finishedAt: string | null; outcome: unknown }[];  // the earlier ones, oldest first
};
type DeliveryRow = {
  id: string; subscriptionId: string; externalId: string | null; receivedAt: string;
  source: 'webhook' | 'hook' | 'emit' | 'cli' | 'poll'; inline: boolean; replayOf: string | null;
  eventCount: number; runs: { id: string; status: string }[];
  events?: unknown[];  // inbound.delivery only
  request?: unknown;   // inbound.delivery only, while it is kept: the request it was received as (inbound.keepDelivery)
};

A run's outcome is the JSON object listen-fire settled it with: { writes, writeRecords?, returned? }, or { error, writes?, writeRecords? } for a failed run, which keeps the writes it made before it failed. A run's status, startedAt, finishedAt, input and outcome are its latest attempt's. writeRecords lists the run's writes (listen-fire runs show); a store that drops it still works with listen-fire, and its runs list no writes. finishedAt is when the run settled completed or failed; a store that answers none leaves listen-fire runs showing null. returned is what the movement returned, as listen-fire records it (at most 64 KiB of JSON, a file by its reference). A store hands the outcome back as it was given (its members may be kept in columns of their own, as @lf/postgres-store keeps them). A store that drops returned still works with listen-fire: its runs show no returned value.

listen-fire --contract-store <state.db|postgres://…> serves these methods over listen-fire's own stores, as a store module on a Unix socket. A module may forward to it, as the test module does (apps/cli/src/__test__/store_module/forward.mjs). runs.status and runs.complete are the contract suite's helpers and are not called by listen-fire.

Changes #

• listen-fire 0.15.2 (adapter protocol 2.8; a module may take it): a runner's requests carry hostRelease, the release of the runner that sent it (The envelope); one without it did not state its sender's release (a runner before 0.15.2, or a host that does not set it). Why: a module serving a 0.12 runner and a 0.15 runner at once must answer each by its own method set, and waits.sweep and inbound.keepDelivery's arrivalMark changed meaning in 0.13 under the same names, so a misread caller gets a wrong answer rather than an error.
• Unreleased (after listen-fire 0.13.0; a store keeps it as it keeps the rest of a state): a resolution and a state may carry members, each member's own { heads, parents? } of a listen through or onto a union, beside heads and parents, theirs together. The listen is one, under one pipeline, so its state is one row.
• 2026-11-02 (listen-fire 0.13.x; a store module that answers unjudged.note must take it): unjudged.note, and each of inbound.keepDelivery's unjudged, carry adapter (the module the arrival came from) and landing (what landed, as its module reported it), which the store keeps and unjudged.list answers. Why: @lf/system never reports an arrival that is itself one of its Arrival Not Judged events, and knew one by a prefix of the record id it minted; it now compares the landing's Kind on its own Events, which needs the landing kept. @lf/postgres-store's migration 17 and the SQLite state file add arrival_unjudged.adapter and .landing; a fact kept before has neither. A store that drops them leaves @lf/system unable to tell its own reports, and two listens on Events that cannot judge them would report each other's, once a poll.
• 2026-10-31, later (listen-fire 0.13.0; a store module that serves several teams must take it): runs.start, events.claim and events.startRun take an optional teamId, as waits.*, work.enqueue, sources.* and parks.commitSegment already do: absent, the tenant the store was opened under. A receipt is its team's (the same listen and key under another team is another receipt), and a run row is kept under its team. listen-fire sends none for its own runs. Why: @listen-fire/embed serves many tenants over one store, and packed the team into listen before. listen-fire's SQLite state file keys event_receipt by team_id (each receipt kept before is the store's own tenant's) and adds run.team_id; @lf/postgres-store already keys both by team.
• 2026-11-01, latest (listen-fire 0.13.0; a store module that answers unjudged.note must take it): inbound.keepDelivery may carry unjudged, the listens that could not judge the delivery's arrivals, kept in its write as unjudged.note keeps each. Why: a poll that a listen could not judge moved its cursor in one write and kept the fact in a second, so a crash between them lost the fact. A store that keeps no unjudged arrivals ignores the field.
• 2026-11-01, later (listen-fire 0.13.0; a store module may take it): inbound.keepDelivery's delivery carries request, the request it was received as, which inbound.delivery answers and inbound.sweepDeliveries forgets past retention; unjudged.note takes attempt and keeps each listen, arrival and attempt once; unjudged.list takes pipeline and pages by attempt too. A store that drops request still works, and no delivery it kept can be replayed. Why: a listen that could not judge an arrival (a provider's lookup failed) is put through the delivery again once the provider recovers (listen-fire listens replay), and each replay that still cannot judge it is reported once. @lf/postgres-store's migration 16 holds arrival_unjudged.attempt and delivery.request; the SQLite state file adds delivery.request. A kept request holds only the headers its module declares it reads (inbound.captureHeaders, never a signature header), its body and query without the fields its module declares (inbound.redactFields), and the ids of the arrivals its delivery brought; the rest of the body is as received, and may hold what the provider puts in it.
• 2026-11-01 (listen-fire 0.13.0; a store module may take it): unjudged.note keeps each listen that could not judge an arrival, once per listen and arrival, and unjudged.list pages them; a store that answers method_not_implemented keeps and reports none. Why: listen-fire takes every delivery, so a listen it cannot judge is reported by @lf/system (Arrival Not Judged), never left to a provider's retry. @lf/postgres-store's migration 16 and the SQLite state file add arrival_unjudged.
• 2026-10-31 (listen-fire 0.13.0; a store module may take it): what the records door reads (system-events.md). runs.failed pages the failed runs, releases.note keeps each release the store is opened under once and releases.list pages them; a store that answers method_not_implemented to any of them reports none. waits.open takes the record's recordId, and waits.stranded answers it. Why: @lf/system reports a failed run, a release and a wait that lost its record, with the record it lost. @lf/postgres-store's migration 15 and the SQLite state file add wait_row.record_id, release_seen and an index on failed runs.
• 2026-10-31 (listen-fire 0.13.0; a store module must take it): the write ledger. writes.record keeps each record write a run sends, with the run's place in its chain of writes and arrivals and when it was sent, and forgets those sent before forgetBefore; writes.depth answers the deepest write of a record since an instant. Why: suppress_self leaves the language, and the host breaks loops itself. An arrival on a record a run wrote within lf.yaml's loopWindow continues that run's chain, and a chain past loopDepth pauses the listen that would continue it (LISTEN_LOOP). listen-fire calls them for every run that writes and every arrival that fires a listen, and a store module that answers method_not_implemented fails there, naming the method. @lf/postgres-store's migration 14 and the SQLite state file add write_ledger. A store that cannot answer writes.depth fails the arrival's delivery (it is tried again), and one that cannot keep writes.record fails the run's write call after the write was sent: the loop breaker is never silently off.
• 2026-10-31 (listen-fire 0.13.0; a store module must take it): listens.hold, and held in a listen's state. A paused listen counts each arrival it does not run, so listen-fire listens can say how many were held; they are counted, not kept, and a resume clears the count and does not run them. An arrival a listen does not run takes its receipt (events.claim), so a provider's redelivery of it is neither counted twice nor taken for the start of a new chain. A store that answers method_not_implemented for listens.hold fails the delivery that holds an arrival, naming the method.
• 2026-10-31 (listen-fire 0.13.0; a store module must take it): the arrival log is swept per record, and a delivery opens its runs' waits as it is kept. waits.sweep takes { limit } and answers { swept }: an arrival goes once no live wait reads it and it is at or below the floor, the lowest mark an unexpired run lease kept (leases.claim keeps waits.mark as it claims), else the latest seq; before is gone. waits.log takes resendWindowMs, and the store keeps each identity apart from its entry for that window, so a re-send after the sweep is still a repeat. waits.sweep may take floor, a mark the caller's own running steps hold in its process: nothing above it goes either (@listen-fire/embed holds each step's, since a run it starts takes no lease). inbound.keepDelivery takes waits (the runs it queues, each on its trigger, from the mark before the delivery's arrivals, the trigger's own arrival pre-noted) and arrivals.resendWindowMs, and answers arrivalMark, the mark before the arrivals (it was the one after). A delivery's source may be poll: a poll of a listenable edge that fires a listen is kept as a delivery, its arrivals and its runs' waits in one write, with no events. work.bury of a fire_event row drops the waits opened under it for runs that never started. Why: a run a delivery queues missed the replies that landed while it sat in the queue, and the sweep by age could forget an arrival a slow step was about to read. @lf/postgres-store's migration 13 adds lease_mark, arrival_identity and wait_row.fire_key, drops the wait's foreign key on its run (a delivery's wait exists before its run does), and lets a delivery's source be poll. work.completeKey ({ key }) completes a row its caller queued a run lease out and ran itself, unless a drain holds it, and drops the waits opened under it for runs that never started: a delivery's arrivals that a request runs itself (/hooks, listen-fire run --webhook, listen-fire run --poll) are a real fire_event row, so their runs' waits are live while the runs start, and a drain retries them if the process dies. A poll that fires keeps its cursor, its arrivals, its runs' waits and one fire_event row in one inbound.keepDelivery; the row carries the runs it minted (runs) and the poll (polled). inbound.keepDelivery refuses waits sent without arrivals.
• 2026-10-31 (listen-fire 0.13.0): listens.states, listens.claimResolve, listens.saveResolution and listens.setPaused keep what each listen whose earlier hops listen-fire resolves (listen to f-[b:Boards WHERE …]->-[:Notes]->) was last resolved to, why its last resolve failed and why it is paused, under a hold that lets one process resolve it at a time; a resolve never writes paused, and a pause never writes the rest. listen-fire calls them for every such listen, and a store module that answers method_not_implemented fails it there, naming the method. @lf/postgres-store's migration 12 and the SQLite state file add listen_state. A resolution and a state may carry parents, the records each hop reported per record hangs off; a store keeps it as it keeps the rest of the state.
• 2026-10-31 (listen-fire 0.13.0): stranded waits (stranded-waits.md). waits.log answers { wakes, stranded }: a gone arrival strands the waits parked on its record, and a later arrival on the record clears that and wakes them. parks.commit and parks.commitSegment strand a wait they park on a record already gone. waits.open's key may be null, for a record already gone: one such wait per run and edge. waits.arrivals answers no gone. waits.stranded is new: one run's stranded waits, or every run's a page at a time. @lf/postgres-store's migration 11 and the SQLite state file add stranded_at and let a wait's key be null.
• 2026-10-31 (listen-fire 0.13.0): callbacks and the awaits keyed by a correlation retired. listen-fire no longer calls callbacks.*, correlations.* or records.closeRun, and parks.commit takes no { kind: "await" } park: an await waits on a listenable edge (waits.*). A store module may still list them; nothing calls them. @lf/postgres-store's migration 10 and the SQLite state file drop their tables: a run parked on a callback under 0.12 cannot resume on 0.13.
• 2026-10-30 (within adapter protocol 2; listen-fire 0.13.0 calls them for the arrivals modules report and for await on a listenable edge): waits on listenable edges. waits.mark, waits.log, waits.open, waits.arrivals, waits.note and waits.sweep keep the arrivals modules report and the waits runs keep open on them; parks.commit takes { kind: "wait", waitId }, and any park at an address unparks the run's wait parked there before; leases.dropRunState drops a run's waits. inbound.keepDelivery may carry the delivery's arrivals, logged in its write, and answers the wake rows it queued (wakes): listen-fire sends them only for a delivery that reports arrivals, and refuses a store module that keeps one without answering wakes. A store module whose manifest does not list waits.log keeps no arrivals: listen-fire refuses a delivery that reports some before keeping anything of it (503 arrivals_not_kept, so its sender sends it again). waits.log skips a repeat of an arrival it logged within the retention, and queues a wake_await row for each wait it answers in its write. waits.note may name the leaf the noting segment resumed: such a note is kept by parks.finishLeaf of that leaf, parks.commit at its address, or parks.commitSegment that resumed it, and dropped by its next parks.claimLeaf, so a crash between a note and the segment's next commit loses no arrival. waits.note may carry the segment's fence, refused when the lease is lost. parks.commitSegment keeps a segment's joins, its parks, the end of the leaf it resumed and the run's settle in one fenced write, and queues in that write a wake for each wait it parks whose arrivals are unread; listen-fire calls it at the end of every segment that parked, recorded a join, resumed a leaf or settled a race, and fails the run of a store module that does not answer it. A race a resumed arm wins is settled by a later step of its run: parks.commitSegment queues it in the arm's write as a settle_race work row (owedRaces) and deletes it in the write of the step that settles it (settledRace); parks.owedRaces lists a run's, joins.deleteFrames drops those at the frames it deletes, and leases.dropRunState drops a run's. A store module must answer parks.owedRaces: listen-fire reads it as each segment ends, and a module that answers method_not_implemented fails there, naming the method. The cases every store is held to are undefined. @lf/postgres-store keeps them from its migration 9.
• 2026-10-27, later (within adapter protocol 2): runs.rerun starts a failed run's next attempt (listen-fire runs rerun), and a run row may answer attempt and attempts. A failed run's outcome keeps the writes it made (records.markFailed and runs.settle with failed alike). A store that answers no attempt or attempts still works, its runs each one attempt; one without runs.rerun works for everything but listen-fire runs rerun. @lf/postgres-store keeps them from its migration 8, and now keeps writeRecords as well.
• 2026-10-27 (within adapter protocol 2): a run row may answer finishedAt, and a run's settled outcome carries writeRecords. Both are optional: a store that answers neither still works, and its runs show no finish time and list no writes.
• 2026-10-22 (within adapter protocol 2; listen-fire 0.12.0-rc.9 requires it): a delivery's receipt. inbound.keepDelivery takes the delivery (the events it produced) and answers { kept }, false for a redelivery under the same externalId at the same subscription, which writes nothing. Every store module must take the new shape: listen-fire treats a null answer as malformed. inbound.deliveries, inbound.delivery and inbound.sweepDeliveries list, read and forget kept deliveries, and inbound.forgetDeliveryId clears a kept delivery's externalId. runs.start and events.startRun take deliveryId, and a run row answers it. runs.status, runs.complete and records.closeRun, served all along, are now in the table.
• 2026-10-20 (within adapter protocol 2): a run's settled outcome may carry returned, what its movement returned. No method changed: a store that hands the outcome back as it was given keeps it.
• 2026-10-20 (within adapter protocol 2): a crash never tears listen-fire's state. parks.commit, events.startRun and inbound.keepDelivery each keep in one write what listen-fire wrote in several; runs.lapsed finds the runs whose worker was lost, which listen-fire fails; work.claimDue's rows carry attempts, work.release says why, and work.bury keeps a row that gave up dead, so a failing row is no longer retried forever.
• 2026-10-19 (within adapter protocol 2): processes.list and processes.swap, the list of module processes the hosts on a store started, written by compare-and-set on its version so two lfs on one store never overwrite each other's entries. listen-fire used to keep it in an inbound checkpoint row.
• 2026-10-19 (within adapter protocol 2): the methods ride adapter protocol 2's HTTP, as every module's do; the stdin/stdout JSON-RPC wire is retired. A lost lease is the error code run_lease_lost (data: { runId }). A store module may be remote (url:).
• 2026-10-18 (within adapter protocol 2): work.claimDue takes kinds, for drain pools (listen-fire drain --kinds).
• 2026-10-17 (within adapter protocol 2): the store slot's wire, and process modules filling the store slot.