Release Notes
Latest: 0.46.2 (2026-11-22). Upgrade with
uv add barca@latest or pip install -U barca. Each release’s notes
are also its GitHub release; changes
merged since the latest release are in
CHANGELOG.md under Pending.
Highlights
Section titled “Highlights”0.43.0 (2026-11-16). The web UI opens on what is wrong and where: a health map of the
project or group beside its causes, biggest first, with one health per node (failing,
blocked, suspect data, behind, waiting) counted the same everywhere. barca records row
counts and flags output that is empty or sharply changed, a run says why it ran and who asked
for it, schedules say when they are late, and a run of tens of thousands of steps opens at once.
0.42.1 (2026-11-14). A busy barca serve stays responsive: while runs write results, the
web UI’s read routes answer in about 100 ms on a 470k-result database, where GET /state took
2.4 s. barca.sh is organized by task, with new pages on why a step did or didn’t run, the
server, tokens and the web UI.
0.42.0 (2026-11-09). Repair one key of a partitioned asset: upload replacement data or pin
an earlier version of just that key, from the web UI’s key explorer or with
barca pin 'asset[dimension=value]'. The web UI has one navigation in the sidebar, a key
explorer that shows every key of a partitioned asset at once, and a quieter layout.
Every change, by version:
Releases 0.1.2 to 0.23.x have their notes only on GitHub Releases, apart from the upgrade notes for 0.10.0 to 0.20.0 kept below.
Changelog
Release notes for barca, newest first: each ## <version> (<date>) section is published as that
version’s GitHub release body, and changes not
released yet collect under ## Pending. Releases 0.1.2 to 0.23.x have their notes only on
GitHub Releases, apart from the upgrade notes kept below for 0.10.0 to 0.20.0; the “0.1.2 to
0.8.0” summary below lists what the earlier of them shipped.
Pending
0.46.2 (2026-11-22)
Bug Fixes
-
A batched node (
batch=) is never called with a single key (fixes #1099; affects 0.32.0 to 0.46.1). A worker lease that started with a step of another node could take the first keys of a batched call into it: the lease was sent without the call, so the function got a bare key where it takes a list, and those keys were written empty (or wrong) with no batch id while the rest of the call ran normally. A lease now never mixes keys of a call with other steps. As further guards, every key of a batched node that is loaded without a planned call gets a call of its own (and the run warns that the plan gave it none), and a worker that is handed a step of a batched node with no call runs it as a call of its one key. On 0.32.0 to 0.46.1,weight=2on a batched node avoids the problem (a step with a weight above 1 is leased alone).It can happen on a cold first run, with no cache eviction and no warm cost estimates.
Upgrading does not repair results already written. A key written empty under an unchanged run hash stays a cache hit, and so do the consumers that read it.
To find affected keys, query the project’s metadata database:
select run_id, node_id, batch_id from materializations mwhere status = 'success' and rows = 0and exists (select 1 from materializations pwhere p.node_id = m.node_id and p.run_hash = m.run_hashand p.id < m.id and p.status = 'success' and p.rows > 0)This misses a key whose first run was empty (no earlier non-empty row) and a wrong result that is not empty. Also check
rows = 0on any node that must never be empty, downstream nodes included, andbatch_id is nullon batched nodes.To repair, refreshing only the batched node is not enough: its consumers stay cached on the empty results. Refresh the batched node and run every final target that reads it:
BARCA_POOL_SIZE=1 barca get <final target> --refresh <node> --batch <node>=allKeep the pool at 1 (on a server, capacity 1, which is one worker) because of the known issue below.
Known issue, not fixed in this release: a run that contains a batched node split across two streams can stall on a pool of 14 or more workers (pool size 2 in one pipeline). A pool of 1, and a server at capacity 1, do not stall. See #1100.
0.46.1 (2026-11-21)
Bug Fixes
-
The scheduler bounds metadata waits and coalesces delayed live slots to one run per schedule. A queued scheduled run and its restart cursor are committed together (#1087).
-
A writable server restarts its scheduler after an unexpected exit. Health and the optional schedule summary report scheduler progress, the current wait and restart history. Health reports degraded during restart backoff or when the loop stalls (#1087).
-
Metadata trim no longer burns time and holds the metadata lock while freeing nothing. Inside
barca serve, automatic trim keeps the used size under the share; the file shrinks onbarca gc: a pass works to the pages that hold data, never runs a fullVACUUMor a checkpoint under the lock, and waits at most 250 ms for each lock before it stops (busy). On a server that is never idle, automatic trim does not remove history (old results, old runs and logs): while any run is running or queued, of any owner (a failed check counts as running), it clears component records and run reports only and reportslive_run; runbarca gcin a quiet window. Safe online history removal is planned for 0.46.2. A CLI command (barca get,barca run) trims as before, compacting when no run is alive. A database from an older format that lacks an index the online pass needs is skipped (needs_gc) instead of failing every command. A pass that freed nothing backs off from one minute up to 30, starting sooner when the file and its log grow by a tenth, 200 more runs finish, orbarca gcruns; the backoff and the last outcome survive a survey andbarca gc. The last pass is indisk_usage.metadata_trimofbarca status --jsonand the server’s status (bytes before and after, used bytes, records cleared per tier, the longest lock hold, andreason:busy,needs_gc,live_run,nothing_eligible,vacuum_deferredor null) (#1082, #1087). -
Cache lookups now reset their prepared SELECT when the lookup ends, so a read-only observer releases the SQLite read snapshot as soon as it has its result (#1087).
-
A worker whose DuckDB database is invalidated (after a DuckDB fatal or internal error, every later statement in the process fails with
FatalException: database has been invalidated) is replaced, and the step that hit it is tried once more in a fresh worker, whatever itsretries. The worker used to stay in the pool and every DuckDB step it was given next failed the same way: one fault became 1,462 failed steps in one run (#1083).
0.46.0 (2026-11-20)
-
Internal:
barca-coreis dissolved into crates that match its layers (barca-store,barca-decide,barca-run,barca-analysisandbarca-service, the one crate the CLI and the server import), with child processes and the socket protocol inbarca-proc, the Python frontend inbarca-pythonand the graph inbarca-model;barca-decide,barca-analysisand planning (barca-compile) take a graph and do not depend on the frontend (docs/engineering/crate-split-2.md, #1056); no behavior change. -
Internal: before that split, the layers were made real inside the crate (#1056): helpers and types moved to the layer that owns them, the storage modules name no higher layer, the dry-run prediction and run sizing moved out of the run orchestrator into the decisions layer, the read models (status, health, rollup, estimates) depend on each other in one checked order, and the renderer is named by nothing below it (a run’s progress lines live with the run orchestrator). The wrong-way module edges went from 42 to none and the largest dependency cycle from 38 modules to none; each crate keeps a layering test. No behavior change.
-
Internal: barca-compile’s modules have a checked dependency order and no longer form a cycle (#1056); no behavior change.
-
Internal: barca-server’s modules have a checked dependency order (
docs/engineering/server-layering.md, #1056): the 13-module cycle is gone, the server’s state is seven sub-states in place of 26 fields and a handler takes the one it uses, andhandlers.rsis split by route family. Its unit tests no longer create.barcain the crate’s source directory. No behavior change. -
Internal: the graph barca plans is an intermediate representation of its own (
barca_model::ir: a node is its declaration, an opaque definition fingerprint, how to invoke it and the frontend’s findings), produced by the Python frontend and no longer the parser’s type; the graph and planning modules of barca-compile name no frontend module, and a test shows a graph written as JSON and read back plans and hashes identically (docs/engineering/ir.md, #1056). No external format, no behavior change. -
Internal: the CLI turns a command into one checked request and decides in one place where it runs (this machine, a named or configured server, this project’s
barca serve), from one table of where each command can run that the--server/--localusage errors andbarca docs server-modeare held to; its modules have a checked order with no cycle (docs/engineering/cli-layering.md, #1056). No behavior change;barca docs server-modenow lists every command--serverand--localapply to (queue,pause,resume,cancel,pin,unpinandgcwere missing). -
Internal: the web UI’s unit tests and kit page read what the server computes from files a Rust test generates from a fixture project (
ui/src/lib/testdata/served/, regenerate withBARCA_UPDATE_SNAPSHOTS=1 cargo test -p barca-service ui_fixture) instead of from values typed by hand, and the fixtures’ own table from a health to a reason and a cause is gone (#1056); no behavior change. -
Internal: run detail, the run list, the run queue, a schedule’s entry, pauses, pins and a server’s health are typed views computed in one place (
barca_service::served, #1056).barca history RUN_IDandGET /runs/{run_id}read one function, the server passing the runs it holds in memory as an overlay;GET /runsisbarca history’s list with that overlay on top.GET /health,/schedule,/pauses,/pins,/project,/auth/status,/auth/tokens,/runs/{run_id}/logs, the202ofPOST /runsand the answer ofDELETE /runs/{run_id}are structs in place of hand-built JSON, byte for byte what they were (a test compares each with the old body); the CLI rendersbarca queue,barca pauseandbarca resumefrom them and the web UI imports their generated TypeScript in place of 12 hand-written copies. No route’s keys, types or words change; a schedule’s times stay unix seconds inGET /scheduleand RFC 3339 inGET /state. -
Internal: the Python helpers Rust starts share one envelope (request, stdout guard, lifeline, exit),
barca sqland the server’s query helper share one tables module, and the worker’s single-step and batched runners share one step lifecycle; no behavior change (#1056).
Breaking
- In a project where
barca serveis running,barca getandbarca runare submitted to that server’s run queue instead of running in the command’s own process (#1056, #1054). The server now listens on a Unix socket in its project,.barca/serve.sock(.barca/envs/<env>/serve.sockfor a named environment), and a command typed there finds it. Before, the command knew nothing of the server, opened the same metadata database and waited on its lock; behind a server recording runs that wait could end after 60 seconds intimed out ... waiting for .barca/metadata.db.lock. Nowgetandrunwait for a run slot, the server executes its deployed files (not an edit it has not loaded), and the result prints as with--server; stderr says once[barca] server .barca/serve.sock (this project's barca serve; --local runs on this machine). Replacement:--localruns the command in its own process as before (barca get total --local).status,history,stats,logs,sql,queue,pause,resume,pin,unpinandcancelare answered by the server the same way; with a--read-onlyserver the reads are answered and a write is refused with a pointer to--local. With no server nothing changes and the check costs one or twostatcalls.barca docs server-mode(“In the server’s own project”) has the table.
Features
-
A requested run can queue last (experimental):
barca get/barca runwith--queue laston a server (--server, or in the project abarca serveis running in), or"queue": "last"in the body ofPOST /runs, joins the run queue behind every waiting run, the scheduled ones included, and is ordered with scheduled work from then on: for a run slot (the scheduled runs and the runs queued last start in the order accepted; no slot pastmax_runs) and for the shared capacity (its steps wait as a scheduled run’s do,scheduled_max_wait_secondsincluded). For starting a large backfill by hand without delaying the schedules. The default is unchanged: a requested run still starts ahead of waiting scheduled runs.queueis"last"in the answer ofPOST /runs, on the run’s entry inGET /queueandbarca queue --json(the table saysqueued last) and inGET /runs/{run_id}while the run waits or executes; the place survives a restart while the run waits.--queueis a usage error (exit 2) on a command that runs on this machine. Seebarca docs serve-ops, “Queue a run last” (#1056). -
A node’s last attempt and typical run time, and what a pause would cover, are served; the web UI stops working them out (#1056).
barca status --json,GET /stateandGET /nodesrows gainlast_attempt(never_run,successorfailed:failedwhen the last materialization failed or any key last failed) andtypical_run_seconds(the median of the node’s recent successful executions, times its number of keys for a partitioned node;nullwith none on record).barca pause TARGET [--downstream] --dry-runpauses nothing and prints what the pause would cover (coversin its JSON,GET /pauses?target=&downstream=): the nodes the target names, the nodes below them, and the schedules whose ticks reach them, each with how (self,target,input,downstream), found by the scheduler’s own walk. The web UI reads these in place of its own arithmetic and graph walk, so its “Blast radius” lists the schedules the scheduler would actually hold back: a schedule above aManualasset is no longer said to reconcile it, and a schedule elsewhere whose tick computes a node below the asset is now listed. All three are experimental (barca docs status-fields, “Last attempt” and “Typical run time”;barca docs incidents, “What a pause would cover”). The check that the UI only renders (scripts/check-ui-layering.py) now also reads run, step, queue and materialization statuses, what each kind ofui/src/libmodule may import, and requires every count, order or produced word it can see to be registered with a reason. -
barca servelistens on a project socket, owner-only and without a token (#1056)..barca/serve.sockserves the same HTTP API as the TCP address. The file is mode0600, and a request over it needs noBARCA_SERVER_TOKENeven with project tokens on: whoever can open it can already write the database beside it. The server removes it when it stops; a killed server’s socket refuses connections, is ignored by commands and is replaced by the next server. A project path too long for a Unix socket leaves the server without one, with a warning at startup. Specified inspecs/behavior/execution.md(“A command beside a server”),specs/behavior/server-authentication.mdandspecs/interfaces/dot-barca-layout.md. -
POST /gc, andbarca gcbeside a server is run by the server (#1054, #1056). The eviction takes its turn with the server’s own writes, and the server protects what its runs in flight hold result by result instead of holding back every current result.barca gc --localevicts in the command’s own process;barca gc --server URLasks a server to evict its own cache.--serverand--localare now accepted bygc(and named in the error for commands that take neither).
Performance
- A barca process keeps one connection to the metadata database, and the read commands do not take its lock (#1056, #1054). Every database operation opened the database twice and closed it, and the read commands (
status,history,stats,logs,doctor, whatsqlreads) queued on the lock with every writer. A process now keeps one connection for its lifetime, still taking the lock for each operation, and checks under the lock that the files at the path are the ones it has open (a restore or reset gets a new connection); the read commands read the database in place, as a server’s routes do. Measured on release builds: a trivialget --refresh-allopens the database 4 times, down from 16, with coordinator CPU 8.0 ms against 10.6 ms (median of 40) and the same peak memory;scripts/perf-gate.py’s 5,000-key incremental run 9.4 to 10.0 ms of CPU against 15.0 to 23.3 ms.BARCA_TRACE_TIMING=1prints how often and how long a command held the lock, and eachVACUUM. After a read command, an emptymetadata.db-waland a 32 KBmetadata.db-shmstay beside the database until the next command that writes ends (a read-only connection cannot remove them;barca docs layout). Design and safety tests:docs/engineering/metadata-owner.md.
Bug Fixes
-
GET /runsstays prompt on a server that has finished many runs (#1056). A server remembers the runs it finished in the last hour, and the run list asked the database about each of them on every request: a page of 50 took 0.8 s beside 2,000 finished runs on a server doing nothing else (0.4 ms a run; 0.41.0 measured the same). It now asks only about a run that is still going or never wrote its row: 5 ms for the same page. A finished run whose row the metadata trim has deleted is no longer listed again from the server’s memory. -
A run list never counts fewer runs than it lists (#1056).
GET /runs,GET /historyandbarca historycount the runs and then list them, each read at its own moment beside a server that is recording; a run recorded between the two was listed without being counted, so a response said"total": 18over 19 runs with"truncated": false. Found by holding a realbarca serveup for ten minutes beside CLI processes (tests/simulation/owner_serve.py, new); the total is now at least the number of runs listed. -
A process waiting for the metadata lock gets a turn (#1054, #1056). A process that took the lock again right after releasing it (a trim’s batches, a run recording step after step) left gaps of microseconds, and waiters, which poll, found one only by chance. A waiter now marks the lock file (its modification time; the file stays empty) and the holder leaves the lock free for 8 ms before its next operation. On a 5.2 GB metadata database (
benchmarks/metadata_lock/fixture.py),barca gc --localtrimming it beside a loop ofbarca get --local: 37 runs finished and none failed, the longest wait for the lock 11.8 s (oneVACUUM); before, 7 finished, one failed after the 60 s wait, and the longest wait was 57.7 s. The trim’s run deletions hold the lock for at most about 100 ms a batch (up to 1.1 s before) and eviction marks are recorded 1000 at a time.VACUUMremains one hold (3.4 to 4.8 s on that database), and runs only when no run is alive. -
A number the CLI reads from a server is printed as the server sent it (#1056).
barca history --server --jsonand the other commands that read a server’s answer into a typed value could print a float one unit in the last place off (about one value in fifteen), so the same run’selapsed_secondsread differently here and through a server. JSON floats are now parsed exactly. -
barca history RUN_ID --json --limit Nsays where the rest of a run’s steps start, as a server does (#1056).steps_page.next_offset(the position of the first step not listed) was set only when the run was read through a server; the same run read from this machine’s database hadtruncated: trueand nonext_offset. Both read one function now. The key is absent, as before, when every step is listed. -
The web UI reads four more answers from the server in place of working them out (#1056): a grouped page’s
N runningis its scope’srunningin the rollup, a partitioned node’s waiting keys on the graph are its servedbehindandblocked, the Schedules page reads a schedule’s standing, next slot and pause fromGET /statealone, and a failing row’s error line on Assets, Tasks and Sensors (and a blocker’s in the node panel) is its root’sdetail. A node declared in several groups now counts as running only under the group the rollup counts it in, as the health bar beside it already did. Code with no importer is gone. -
barca statusand a server compute health, schedule standing and estimates from one implementation, and agree on a typical duration (#1056). The server rebuilt whatbarca statusbuilds, and the two took a node’s typical duration differently: over an even number of recent successful runs the server took the lower of the two middle values,barca statustheir mean. For a node with runs of 0 s and 12 s,GET /stateestimated it fresh 5 s after its schedule’s next tick andbarca status10 s after. Both now fill one inputs type in barca-core and read the mean of the two middle values, as schedules’ typical times already did. What changes on a server for a node with an even number of samples (at most 20):durations.median_secondsofGET /state, and what is made of it there and inGET /nodes,GET /state/rollupandbarca.nodes(expected_fresh_at, a root’saction.estimated_seconds).durations.p95_secondsis unchanged (nearest rank), and so is everythingbarca statusprinted. No key or type changes. -
The error after 60 seconds of waiting for the metadata database’s lock names the process holding it (#1054).
timed out after 60.0s waiting for .barca/metadata.db.lock: another barca process is holding the metadata DB (held now by pid 4312 (barca serve --port 8274)), read from the kernel’s lock table on Linux (elsewhere it says the holder could not be named), with a pointer to the server in the project.BARCA_TRACE_TIMINGprints how many of a run’s lock acquisitions waited, their total and the longest. One read of the kernel’s lock table can skip a lock that is held while other locks are taken and released (about one read in a hundred with four threads doing so), and the table identifies a file by an inode number that another filesystem repeats. The table is now read up to five times, a process is named only if it has the lock file open, a lock found free meanwhile is taken instead of reported, and a holder the table does not list (outside this container, or on another machine) is reported as that.
Documentation
- CI’s merge tier runs the Rust tests a change can affect, not the whole workspace (#945, #1056).
scripts/ci-rust-tests.pymaps a diff to the crates that own the changed files, the crates that depend on them (read fromcargo metadata) and the tests that read a changed file from outside their crate (site pages, specifications, UI fixtures, the guards that scan every crate), and prints the reason for each crate in thechangesjob. A change insidebarca-serverruns 300 of the 1,578 tests and a site page 95; a diff no Rust test reads runs none. The root manifest,Cargo.lock, the CI workflow,python/barca/and any path the script does not know still run everything, as does a release (the full tier) and a pull request labelledci-full.scripts/check-fast.shuses the same selection;--rust-allruns every Rust test. A test broken by a change the selection considers unrelated is found by the next release’s full tier, not at the merge.
0.45.0 (2026-11-19)
- Run counts reflect active worker steps. Queue and history rows summarize multi-target runs, the queue explains its extra requested-run slot, and run details distinguish attempts, steps, planned nodes and unreached work (#1042).
Breaking
- On a server with a shared capacity, a requested run’s steps go ahead of a scheduled run’s (#1003). With
[server] capacity(orbarca serve --capacity), steps were admitted first come, first served across runs, so a run someone asked for that overlapped a scheduled run took turns with it step by step: atcapacity = 1, a request of 85 steps that took 43 s alone took 202 s beside a scheduled run of 110 steps. Now a step of a requested run (POST /runs, the web UI, a--serverclient, an agent: anything a schedule’s tick did not start) is admitted before a step of a scheduled run, and the request takes 44 s; the scheduled run’s own wall time was unchanged in the runs measured. Requested runs are admitted in the order they first asked, not interleaved with each other, and scheduled runs likewise. Nothing running is stopped. A scheduled step that has waited[server] scheduled_max_wait_seconds(default 120) goes next, so requests cannot starve a schedule; the bound is per step, so under requests that never stop a scheduled run advances about one step per bound. A run now gives back the weight of a step that ended in the same call that asks for its next step, so another run cannot take it in between.[server] admission = "first_come"restores the old order.GET /queuecapacitygainsadmission,scheduled_max_wait_secondsand anorigin(requestedorscheduled) on each waiting step, and the web UI’s waiting steps show it.barca docs serve-ops(“A capacity shared by every run”) and the resources specification (version 3) state the rule.
Features
-
Freshness rollups put roots that need someone first, label aggregate gap in node-time, and show a one-time command for unscheduled chains. Group tables put actionable groups first and root panels show what they hold (#1041).
-
Status reports cause counts, filters by cause, health or root, scopes groups by name and reads a server rollup at the current second with
--now. Usebarca cancel RUN_IDto cancel server work (#1043, #932). -
The key explorer renders served keys, and the graph view and the sidebar use the health map’s words and colours (#1036).
barca status NODE --keystakes the explorer’s filters as flags, all of which must hold:--state,--needs-run(the keys a run computes),--value DIM=V[,V](repeatable),--range DIM=FROM..TO(a stretch of a dimension, in its own order),--error N(one error group’s failed keys) and--match TEXT;--sort key|state|attempted|elapsed|size|rowsorders them and--offset Npages them with--limit. Its JSON gainsoffset,needs_run(how many of the keys that match a run computes),selection(what matches asbarca get --partitiontakes it: a rectangle when the keys form one, a list of keys otherwise) and each key’svalues; the table prints how many keys match and thebarca getline that computes them, and numbers the error groups.barca status NODE --overviewis new: the counts, what is wrong and where (each error of the failed keys, then the blocked, stale and never-run keys, with the dimension values they sit in and the commands that list and run them) and the grid’s rows. A server answers both itself, with the function a local command uses:GET /assets/{name}/partitions/keys(state,needs_run,value,range,error,q,sort,limitup to 1000,offset) andGET /assets/{name}/partitions/overview;--serverprints the same text and JSON, and reads page after page for--all. The web UI’s key explorer draws these two answers and no longer downloads and decodes the whole grid: a filter, an order or a scroll asks the server for a page of 200 keys, so a node with 100,000 keys costs the browser about 45 KB a filter (the grid it read before was 2.3 MB) and the route 1 to 25 ms; its column headers order the keys.GET /assets/{name}/partitions/keyandbarca status NODE --key --jsongainneeds_run. The graph view’s cards, a group’s card, the legend and the sidebar’s lines for files and groups read as the health map does (failing,overdue,no refresh path,queued,undecided,catching up,fresh), each a dot in the map’s colour, in place of the cache-state and health words; a node a failure upstream holds readsfailingand its tooltip names the failing node. Each entry offilesinbarca status --rollup --jsonandGET /state/rollupgainscausesandfresh, which the sidebar reads. The layering table holds three exemptions fewer. Fixed on the way:GET /assets/{name}/versionsandbarca pin --versionsrefused a key of a node with several dimensions in most processes (name exactly one key with every partition dimension), because the dimensions were compared in the order a hash map held them, so the explorer’s key panel often had no Versions section. -
The assets table’s filter chips, row order and key counts come from the server (#992). The chips of the Assets, Tasks and Sensors pages are the health map’s parts (
failing,overdue,no refresh path,queued,undecided,catching up,fresh): a row falls under its servedcause, and with no other filter a chip’s count is the rollup’s own, read from the newkinds(asset,taskandsensor, each{nodes, fresh, causes}, for the whole scope and for each entry offilesinbarca status --rollup --jsonandGET /state/rollup); under a search or another filter it counts the rows listed. Rows are ordered by the served order of the causes, what alarms first, instead of a rank of cache states. “N keys wait on X” and the key bar read counts instead of a state’sdetailsentence: a partitioned node’spartitionsgainsblockedandblocked_on(the keys that wait on the failed keys of an input, and that input’s id) andbehind(the missing keys a run computes), inbarca status --json,GET /stateandGET /nodes; a node entry’skeysin the rollup gainscause, which colours the band of its keys that are behind. Links written with the old chips still open (failed=1andblocked=1readstate=failing,state=cachedreadsstate=fresh); otherstate=values of the old vocabulary are ignored. Every exemption the layering guard held for this issue is removed. -
Every place the web UI shows a state says when it will be fresh, or why there is no estimate (#968). A node’s row and panel read
fresh ~15:05(the server’sexpected_fresh_at, to the minute and rounded up),rechecked 15:00where a tick will only look (recheck_at), orno estimate:with the reason; the panel adds the cause in the health map’s word, the root that holds the node with a link to it, the root’s fact and what clears it, how many ticks missed the node and what the last one found. A group’s row readsall fresh by ~15:02,152 with no estimate, or both, from its rollup entry, in place of “Last success · oldest member”, and the State column, its bar and the page header’s bar use the map’s cause words and colours (1 failing · 84 catching up,all 116 fresh), so a page has one legend; “worst first” orders rows by the servedweight. The Schedules page takes late from the server alone and shows each schedule’s next slot, its typical queue wait and run time, andqueue-boundwith what to do, late and queue-bound schedules first; a waiting run in the queue saysstarts in ~40s. One field is new: every node carriesno_estimate, why a node that is not fresh has noexpected_fresh_at(failing,paused,scheduler_off,no_path,undecided,missed,queue_stopped,no_scheduler_here,not_promised;nullfor a fresh node and one with an estimate), inbarca status --json,GET /state,GET /nodesand as abarca.nodescolumn (barca docs status-fields, “Times”). -
Roots rank by how far what they hold is from fresh, and that distance is served (#1028). The to-do list put every root holding a node with no estimate first, by node count, so a
never runroot whose action is “wait” outranked a change holding four times as many nodes, and a failing node with what it blocks could sit below the first three. A root now carriesweight: each node it holds counts 6 when someone has to act (failing,overdue,no refresh path) and 2 when it will be fresh without anyone acting or barca cannot say (queued,catching up,undecided).roots, and every entry’sheld_by, are ordered by it, the most first, a failure first among equals, then nodes, gap and id. A rollup entry carries the same measure asweight(a fresh node counts 1, so a fully fresh scope weighs its node count) andweights(by cause, and fresh); the web UI’s health map sizes and colours its segments from those two fields and no longer holds a weight table, so the map, the list and the CLI order things by one rule.barca status --rollupprintsDistance from fresh: 1728 (weighted nodes); 698 when every node is freshunder the gap line andweight Non each root;--json,barca status --json(rollup) andGET /state/rollupcarry the fields (specs/behavior/health.md, “Distance from fresh”). -
The Runs page filters on the server, and
barca historyhas the same filters (#969, experimental). On a server that ticks every minute the page was filtering the 100 runs it had loaded: a status chip, the search and a click on a bar of the chart all missed what was not on the page, and “Hide schedule runs” also hid the runs recorded before barca stored what started a run. Now each of them is a query ofGET /runs, by the name of the matchingbarca historyflag, and the list, itstotaland the chart are of the runs the filters keep in the whole history:status(now a list, as--status;not_successfulis every status of a run that ended without succeeding),not_triggered_by/--not-triggered-by(an exclusion, so a run with no recorded trigger stays),sinceanduntil/--until(a window of start times: a bar of the chart is itsatanduntil) andsearch/--search(text in the run id, target or job). The database keeps the runs, each filter from an index, sobarca history --triggered-byand the other filters no longer read every run: on 500,000 runs a status, a trigger or a window answers in a few milliseconds and a text search in about a tenth of a second (a new index,idx_runs_search, built in about two seconds when a database of that size is first opened). The page hides a schedule’s runs until asked and says under the chart how many that is in the last 24 hours and how many of them did not succeed (activity.excluded); the browser remembers the choice.activity(andbarca history --activity, which now takes--status,--not-triggered-byand--search) gives each hour itsuntil, the median time of its finished runs (median_seconds) and what most of its unsuccessful runs say went wrong (failure), which a bar’s tooltip shows; the chart states the time zone its hours are in. Runs in progress come first inGET /runswhateverlimitlists, so a long backfill no longer drops off the page behind a hundred newer runs (#941). A step served from cache no longer reads as executing in a run the server started, nor the node after it as queued (now, therunningfield ofGET /state): a cached node the run has not touched counts as done unless the run was asked to refresh. A finished run’s panel lists its slowest steps. -
A run accepted while
barca servedrains says it waits for a restart (#1011). A draining server still accepts runs and queues them for the next server, but its answer looked like any queued run’s, though the run waits for the whole drain (up to[server] drain_timeout) and the restart.POST /runs, each entry ofGET /queueandGET /runs/{run_id}now carrywaiting_for:"restart"for a queued run while the server drains,nullotherwise.barca get|run --serverprints[barca] run RUN_ID is queued behind a restart (position N): the server at URL is draining and starts no run; it starts when the next server is upon stderr in every mode, and the web UI’s queue marks such a runafter restart. A run accepted during a drain with no server started after it stays queued in the metadata DB until one starts. Experimental;barca docs serve-ops, “Stopping the server”.
Bug Fixes
-
Read-only servers report the writer’s schedules, run slots, queue timing and freshness estimates. A stopped scheduler appears once at the top of the rollup (#1039).
-
A run’s detail and an accepted run read the same wherever they are read.
barca history RUN_IDon this machine counts the run’s planned nodes as a server does (8 steps planned over 6 nodes,counts.nodesin--json), when the files it ran still plan what it ran; before, only a server’s answer had them. In the web UI, a node whose run was accepted readsqueueduntil the run reports on it, where it readrunningbefore 0.45 and nothing after #1042. -
Health estimates respect paused dependencies, keep the first input change as the stale time, and disregard ticks that preceded an upstream recovery. Schedules report failure holds and in-flight skips, and a brief queue wait preserves the underlying change as the cause (#1040).
-
An unchanged
GET /nodespoll is a304again. Itsas_ofwas the server’s clock to the second, so the body and itsETagchanged every second and a conditional poll was answered in full. It is now the start of the current minute, the instantgap_secondsis read at; the nodes are still classified on the clock to the second. -
The transfer helper’s connection no longer breaks or stalls under load (#1001). With a remote artifact store, a run over a
collectof a few thousand cached keys could fail with exit 3,could not fetch N cached artifact(s) ... transfer helper exited, and a large run could leave its uploads undone with the same message. When a new request reached the coordinator while a reply from the helper was only partly read, the bytes read so far were discarded, the next read began inside the reply, and the connection was given up. The coordinator now keeps a partly read frame and finishes it after handling the request, on the transfer helper’s socket and on each worker’s socket, which had the same defect under lighter traffic. With that fixed, the same runs exposed a second defect: the coordinator stopped reading replies while it waited to write a request, and the helper stopped reading requests while it waited to send a reply, so the run hung with both directions of the socket full. The coordinator now reads replies while a request waits to be written, and the helper sends a reply without holding the lock its request reader needs. Against an Azurite emulator, 3,000 cached keys failed 3 runs of 3 before and passed 15 of 15 after. -
A server restart no longer recomputes a step that finished while its upload was in flight (#1002). With a store, a step is recorded once its upload is confirmed. When a run was cancelled before that (the drain timeout of a stopping
barca serve, which puts the run back in the queue, or a Ctrl-C), the upload was abandoned and the step left out of the record, although its artifact was complete on this machine, so the requeued run, or the next command, executed it again: a 3 s step with a 120 MB sink cost about 10 s to redo after a restart. A cancelled run now records such a step and keeps its upload pending, as it does for a failed upload (#390): stderr has[barca] warning: 1 result not uploaded to <store> (...): the run was cancelled before the upload was confirmed; those steps finished, ..., and the next run uploads it from.barca/artifacts/before its own work and takes the step as a cache hit. Changed for a Ctrl-C too:barca docs remoteused to say a step whose upload was in flight is not recorded and runs again; it is now recorded,unsynced(local only) until the upload is done. A step stopped in the middle of its function is not recorded, as before. -
A file sink is a copy of its artifact: a returned relation runs once, and the sink has the artifact’s bytes (#1005). A
@sinkfile in its asset’s artifact format (fromserializer=, else its extension, else the artifact’s) was written by encoding the step’s result a second time. A returned DuckDB relation or Polars LazyFrame therefore ran its whole query again for each sink (a relation of about 8.5 s with a 12 MB local sink took 16–22 s instead of about 9), and a DuckDB aggregate could come out in another row order than its artifact. The worker now copies the bytes it wrote for the artifact (the pinned upload snapshot with an artifact store, else a private link taken before the artifact path was published), so the sink is byte-identical to the artifact; this covers json, pickle, parquet and csv, each key of a partitioned asset, a key of a batched call, symlinked sink paths and remote sink URIs. A cache hit that republishes such a sink copies the cached bytes without reading the value, so it holds what it held when the step ran. A sink in another format and a dataset sink are encoded from the result as before; a value that fell back to pickle still fails a.parquetsink. Sinks are still written inside the step and a failed sink still fails it.barca docs sinks, the artifact-formats specification (version 5). -
Sink time is reported beside each step’s time (#1004). A step’s sinks are written after its duration is taken, so the time they held the worker was in no step: a 355 MB sink left several seconds between steps that nothing accounted for, and a step’s
barca.stepspan ended before its sinks while the worker’sbarca.executespan went on. Steps now carrysink_seconds: insteps[]ofbarca get --jsonandbarca run --json(summed over the keys that ran, and a new--fieldsvalue), inbarca history RUN_ID --jsonandGET /runs/{run_id}(a newmaterializations.sink_secondscolumn; each sink’s own time issecondsin the step’ssinks_json), asbarca.sink_secondson thebarca.stepspan, whose duration now ends after the sinks, and as+ 9.5s sinksbeside a step’s time in the web UI’s run panel.elapsed_secondsis unchanged and stays the step’s own time, so a step’s time with its sinks is the sum of the two (barca docs contract). The worker reports the new fields within protocol version 5, as additive optional metadata.
Performance
- A run no longer reads every key’s whole history to say why it ran (#1009). At each phase boundary the plan-reasons lookup added in 0.43 read every row each missed step ever wrote, to use only the newest row and the newest success, so its time grew with the age of the database. It now reads those two rows of each step by index seeks. Measured at 300 partition keys that all miss, median of 5 runs, on a loaded 32-core machine: with the
fastprofile 1.7, 135 and 873 ms per phase boundary at 1x, 200x and 1000x history (0.5, 50 and 254 MB databases, up to 300k rows) became 1.7, 2.4 and 3.3 ms; with--release1.2, 95 and 711 ms became 1.0, 3.0 and 2.6 ms. It takes a new partial index,idx_mat_node_rest, holding only failed rows and successes without an artifact (a ledger post’s): opening an older database builds it, about 80 ms and 1 MB for 300k rows of which one in seven failed, and older binaries ignore it. CI’s performance gate gains ahistorycheck: 300 keys with 200 times their history, the lookup under 25 ms. barca serveno longer hashes an unchanged cached input again in every run (#1010). With an artifact store, a cache hit’s local copy is hashed against its recorded digest before a step reads it, and a server did that in every run for every cached input it read. It now remembers, for its lifetime, the copies it found to match (by path, device, inode, size, mtime and ctime to the nanosecond) and hashes one again only when one of those changed, so an edited, truncated, replaced ortouched copy is still found and fetched again, whatever its size. A copy written less than 2 seconds before its check is checked once more next time instead of being remembered, a restarted server starts with nothing remembered, and the memo holds at most 131,072 files. Measured with Azurite on a loaded machine, a run that reads 300 cached inputs spent a median of 12 ms (10 to 14) in the check and now 1 ms (0.9 to 1.4), with no requests to the transfer helper; and with 3 inputs of 200 MB (a plain-directory store; the hash is of the local file whatever the store) 135 ms (133 to 137) and now none after the first run, the run taking 0.31 s instead of 0.41 s.barca getis unchanged: each command checks the inputs it reads once. Not detected, as before for the step’s own read: bytes changed below the file system, or a clock set back by more than 2 seconds.barca docs remote, “Checking a local copy against the store”.- Mid-size uploads to S3 go in parallel parts, and a sink’s large files to Azure in parallel blocks (#1007). s3fs put a file under about 105 MB as one request on one connection, so it uploaded at one connection’s speed. Barca now sizes the parts itself: a file of 10 MiB or more goes as a multipart upload of 5 to 50 MiB parts, 10 at a time; a smaller one is still one request. Against MinIO behind a modelled 20 MB/s per connection (+10 ms), 32 MiB uploads in 0.59 s instead of 2.13 s and 96 MiB in 0.78 s instead of 5.24 s; at 5 MB/s, 96 MiB in 2.3 s instead of 20.3 s. On Azure, the files of a
@sink(a multi-file put, which adlfs sent one block at a time) now go 64 blocks at a time: a 400 MiB sink file in 4.2 s instead of 27.1 s at 20 MB/s. A single Azure upload is limited to 64 blocks in flight instead of tens of thousands, so an artifact larger than 64 MiB holds at most 256 MiB in memory instead of the whole file (404 MB for a 400 MiB file before, 259 MB now), at the same speed. Which Azure files go in blocks is unchanged (over 64 MiB): smaller blocks measured faster behind the throttle and slower against Azurite unthrottled, and wait for a run against real Azure. GCS is unchanged.barca docs remote, “What happens during a run”.
Documentation
- A proposal to separate a step being computed from its output being published (#1006), and a corrected drain rule.
specs/proposals/computed-and-published.mdis an unapproved draft from the measurements of #951: a step is recorded and gives its capacity back once its artifact is complete locally, and the store upload and sinks are publications the run settles before it completes. Nothing in it is implemented.specs/behavior/operations.md(version 4) now states what a draining server does with a new request: it accepts and queues it, and the next server runs it. Version 3 said to reject it.
0.44.0 (2026-11-17)
Breaking
barca statusdecides a node below aManualor pinned node as a run does (#985). A run (get,run, a scheduled tick) reads aManualnode, and an asset pinned withbarca pin, as it is and never recomputes it;barca status,GET /state,GET /nodes,barca.nodesinbarca sqland a node’s partition grid predicted a recompute of it instead. So below a staleManualnode they saidstale/upstream_stale(healthbehind), orunknown/cutoff_pendingbehind an@asset(cutoff=True), for nodes thatbarca get --dry-runcalledcachedand every tick found up to date.cache.stateof those nodes changes: a node that is up to date against the held node’s current result is nowcached(reasonmaterialized, healthok), with the run hash a run gives it, and itsdetailnames the nearest stale held node above and the command that recomputes it (up to date against 'baseline' as it is: ...). The held node itself still readsstalewhen its code or inputs moved on, and a held input is no longer a cause ofupstream_stale. A status scoped to targets now lists the nodes above a pinned asset too, and decides the pinned asset for its current code and inputs as the unscoped one does. No value was added or removed. To find what is held back, select thestaleManualor pinned nodes; there is no replacement for the old answer, which described a recompute no run performs. A node paused withbarca pauseis read as it is by ticks only, so status still says what a request would do there (barca docs status, “Cache state”).- A tick rebuilds the
Alwaysnodes below every sensor it polls (#978). Until now a tick’s targets were the scheduled node and theAlwaysnodes below it; a sensor that a target only reads was polled, its new value recorded, and theAlwaysnodes below that sensor stayed out of date through every tick (#952). Now, when the sensor isManual(the default) orAlways, those nodes are targets of the tick too, and so are the nodes below the sensors they read in turn. A sensor with aScheduleof its own is unchanged: what is below it follows its own ticks. The walk from a polled sensor follows the existing rules: it passes aManualasset or task without updating it and stops at a node with its ownSchedule. The targets are fixed by the graph, so a poll that returns the same value still costs only cache checks. What changes for a deployed server:Alwaysassets that sat stale beside a scheduled node are now computed by its ticks, anAlwaystask below a polled sensor now fires when the sensor’s value changes (in each run, when two schedules that poll the sensor fire in the same second), a failure in one of them counts as a failed tick of that schedule, andGET /runs/{run_id}and thebarca.runspan name the wider target list. To keep such a node off the faster ticks, give it aScheduleof its own or make itManual; there is no switch for the old rule.barca_core::freshness::tick_reachreports these nodes asTarget(it andtick_targetsare new in this release, for the refresh path of #961).barca docs scheduling(“A sensor a tick polls”), the scheduling page and the freshness specification state the rule.
Features
-
The health map is sized by how far a scope is from fresh and coloured by what is inside it (#966). A segment’s angle on the Assets page’s map was its asset count and its colour its worst member’s, so a group with 13% of its nodes behind was one solid colour. The angle is now the scope’s distance from fresh in weighted nodes: every node counts 1, a node that needs someone (
failing,overdue,no refresh path) counts 6, and one that will be fresh without anyone acting or that barca cannot decide (queued,catching up,undecided) counts 2, so the room a group takes is how big its problem is and a fully fresh group stays on the map, small and green. A segment is drawn in the colours of the causes inside it, stacked by that weight; each cause has one colour,undecidedis the one grey and the one word for it (“not known yet”, “waiting” and “needs attention” are gone from the map). The centre says the scope in the terms of the gap (“15 failing · 173 no refresh path · 40 undecided”), with “fresh within about 16h” and how many nodes have no estimate under it. The map, its centre, the line beside it and the list count nodes and say so; assets are stated beside them. Sizes come from the rollup’s own counts with a display weight per cause (specs/behavior/health.md, “The web UI’s overview”). -
Causes are a ranked to-do list, and a scope’s list is served (#967). The list beside the map is the open scope’s roots as the server ranks them: what each is and which node it is about, why, what it holds there (nodes and assets, by cause), the gap it holds or how many of its nodes have no estimate, and what to do, with the command to copy and the compute it takes. Every node that is not fresh is under exactly one entry, so no node is listed twice (the old list appended one entry per behind node after the roots); failures with one error are one entry that opens to the others, and data signals (empty output, rows changed, a node older than its input) are a section of their own. The top three roots and how much of the scope they hold (“The first 3 roots hold 392 of 422 nodes that are not fresh”) show without scrolling at 1440×900; “N more” opens the rest in place instead of the Failures tab, which said “Nothing has failed here”. Picking a root lights what it holds on the map and in the table; its node’s name opens the node. For this, every entry of
GET /state/rollupandbarca status --rollup --json(androllupofbarca status --json) carriesnot_freshandheld_by: the roots that hold its nodes, each withnodes,assets,causes,gap_seconds,unboundedandcumulative_nodes, ranked likerootsover what is held in that scope, so a group’s list is its own entry and nothing is filtered or counted in the browser.barca status --rollupprints “The first 3 hold N of them.” above a list of more than three roots. Experimental, with the rest of the rollup. -
barca sqlhas the schedules, the ticks and the run queue as tables, and the manual ships the health queries (#965).barca.schedulesis one row per scheduled node (itsscheduleblock frombarca status --json, withinterval_secondsand thetargetsof one tick),barca.ticksone row per recorded tick (what the scheduler decided, the run it started, how many targets ended each way and, for a schedule’s newest 20 fired ticks, each target’s outcome), andbarca.queueone row per run in a server’s run queue (barca queue --json, withstateand the tick’sscheduled_at). They work inbarca sqlon a machine (the queue is a server’s: there the table is empty and stderr says so), throughPOST /sql/queryand withbarca sql --server.barca docs sql(“Health queries”) gives eight short queries to adapt, each run by the tests as written: the freshness gap as one number, the gap by source file, the top roots by nodes held and gap, the nodes with no refresh path, the overdue nodes with how many ticks missed them, the queue-bound schedules with their typical wait, the tick outcomes of one node over time, and the runs per hour by trigger. Times are text in every table, so cast one to compute with it (now() - stale_since::timestamptz).barca.nodeshas no group column: the gap by group isbarca status --rollup. -
The server answers queries over barca’s own tables:
POST /sql/query(#972, experimental). A browser cannot run DuckDB over a server’s records, so the web UI had no way to ask an aggregate question. The route takes{"query", "limit"}and answers the documentbarca sql --jsonprints, for oneSELECToverbarca.runs,barca.materializationsandbarca.nodes. It is a read (a--read-onlyserver serves it, and--auth tokenapplies), limited to 1000 rows by default and 10000 at most, and to 5 seconds, after which the query is cancelled and the answer is408.barca sql --serversends a query that names only those tables to the route, so that machine needs no DuckDB for it; a query that names a result view runs on the client as before. The server still never runs SQL over results or files: the query runs in one long-lived helper process whose in-memory DuckDB holds barca’s tables only, with file, network and extension access switched off, in a read-only transaction, without the server’s environment variables, so a result view,read_parquet('/etc/...'),COPY ... TO,ATTACH,INSTALL, a second statement or a write hidden in aSELECTis a400. An answer holds at most 4MB of rows (more is a400), and four queries are admitted at once (one more is a429withRetry-After), so a query cannot take the server’s memory or the route. A server whose Python environment has no DuckDB answers503naminguv add 'barca[sql]', and the CLI then runs the query itself.barca docs sql, “Queries the server answers”. -
Every node has a health, computed once in barca (#954).
barca status --json,GET /nodes,GET /stateandbarca.nodesinbarca sqlnow carryhealth(failing,blocked,suspect,behind,undecided,never_run,ok, most severe first) andhealth_reason, the rule that decided it (last_attempt_failed,upstream_failing,schedule_late,stale, …). The rules moved out of the web UI’s TypeScript intobarca-corewithout change of meaning, so the CLI, the API and the UI say the same word, and a node below a failure readsblockedinbarca statustoo. The table prints the words under the cache counts (Health: 1 failing, 1 blocked, 2 ok). The UI’swaitingis nowundecidedeverywhere. Experimental;barca docs status-fields, “Health”. -
Data signals are on every status node, with how much was measured (#957).
signals(empty,rows_changed,behind_input) moves fromGET /stateonly tobarca status --json,GET /nodesandbarca.nodesas well, besidemeasured: whether the asset’s latest result has a recorded row count (nullfor a task or sensor).data_coveragein status JSON counts it ({"assets": 556, "measured": 7, "suspect": 0}), the table printsData: 7 of 556 assets measured, and the web UI states the coverage of the open scope instead of implying that unmeasured data is fine. Experimental;barca docs status-fields, “Data signals and coverage”. -
One rollup of health, for the CLI and the web UI (#955).
barca status --rollupand the server’sGET /state/rollup(same scope asGET /state:?targets=,?files=) answer one tree of everything in scope: the root, each group, the source file of the nodes in no group, and each node. Every level is the exact sum of its children (a node in several groups is counted under the first by group id), in nodes (nodes,health) and in assets (assets,asset_health), with a partitioned node’skeys, the run work underneath (running) and the scope’sdata_coverage;rootslists each failing node with how many nodes it holds (itself and every node it blocks) and the error group it shares. Each status node (barca status --json,GET /nodes,GET /state) gainsroot: the failing node that explains a failing or blocked one. The human form prints groups and files worst first, with nodes and assets side by side. The web UI’s health map, health bars, group rows, causes and failures list now render this response instead of adding rows up in TypeScript, so they and the CLI state the same numbers and each count names its unit: the map counted assets while the bars counted every node. The server sums the status resultGET /statealready keeps; no status is computed for the rollup. In the UI, a failure’s “Waiting on it” column (every node downstream) is now “Nodes held” (itself and the nodes it blocks), a panel names the one failing node that blocks a node instead of every failed node upstream, and a bar shows run work beside the healths instead of in place of them. Experimental: causes, the freshness gap and other root kinds join the same document in later releases. Seebarca docs status(“The rollup”) andbarca docs status-fields. -
barca serverecords what each scheduled tick decided (#960). A new bounded table in the metadata database,schedule_ticks, holds one row per due tick of a schedule: whether it fired, was paused, was skipped for a run in flight (named) or was held back as failing; for a fired tick the run, when it started, how long it waited in the run queue and how it ended; and what that run did with each of the tick’s targets (rebuilt,up_to_datefor a cache hit,failed,not_reached). Until now a tick that found everything up to date, and one that was skipped, left no record. The scheduler writes values it already holds (one write per decision, one at the run’s start and one at its end) and keeps the newest 1,000 ticks per schedule, none older than 14 days, with per-target outcomes for the newest 20 fired ticks. Nothing reads it yet: node health and thebarca.tickstable ofbarca sqlbuild on it. A plain CLI run and a--read-onlyserver write nothing. Known limitation: a polled sensor is recordedrebuiltwhether or not its observation changed. -
A run’s explanation is computed once, in Rust, for the CLI and the web UI (#956).
barca history RUN_ID --jsonandGET /runs/{run_id}carryexplanation(experimental): the steps grouped by the reason they ran (why), retries counted apart from each step’s first attempt, the targets as a list and what became of each, and for a run in progress how far it is with an ETA.barca history RUN_IDprints the same words and the web UI renders them instead of deriving its own. Three wordings change with it: a run of 29 steps that retried nothing says29 steps, no retries(it said29 attempts);why:names the reasons (29 steps ran: 27 sensors (always run), 2 never run, where it said29 steps of 29 nodes were not cache hits) and lists each reason’s rows under its label; and a reason whose nodes each ran one step is counted in nodes with an example (27 nodes, e.g. poll_inbox), where the UI read as one sensor of 27 steps. The run panel lists a run’s targets one to a line.run.plan_reasons,run.attempts,run.retries,run.cancellationandrun.targetare unchanged. -
Every node says which schedule will refresh it, or that nothing will (#961).
barca status --json(and--fields),GET /nodesandGET /statecarryrefresh_path:{"schedule", "next_tick", "paused", "live", "missed_ticks"}, the schedule whose tick has the node as a target, when it next fires, and how many finished ticks had the node as a target and did not leave it fresh;nullfor a node no tick targets (aManualasset or task, anAlwaysnode with no scheduled node or polled sensor above it, a sensor only polled as an input) and for a paused node or pinned asset.barca.nodesgainsrefresh_schedule,next_tickandmissed_ticks. Membership is the scheduler’s own target list, walked once per loaded graph. A paused schedule and one no scheduler fires (live: false:barca statuswithout a server, a--read-onlyor--no-scheduleserver, a schedule held aftermax_failures) are still the path, with nonext_tick.missed_ticksis read from the tick record, so it is bounded by the newest 20 fired ticks of each schedule and is 0 without one. Thebarca statustable addsnext tick 15:05 UTC by inbox,inbox is paused,inbox is not firingorno refresh pathto theWHYof a node that is not fresh, and the web UI’s node panel shows the same. Experimental;barca docs status-fields, “Refresh path”. -
Every node that is not fresh says since when, and when it will be fresh or only rechecked (#962).
barca status --json(and--fields),GET /nodes,GET /stateandbarca.nodescarry three times, RFC 3339 UTC ornull:stale_since(the earliest recorded time from which the node has been out of date: a failure’s first failed attempt, the changed input’s or sensor’s result, a late schedule’s first missed slot; for a code change or a node never run, the source file’s modification time, which is never before the change but moves forward with a later edit to the file;nullfor an environment change, which nothing dates),expected_fresh_at(an estimate rounded up to 5 seconds: the start of the run that will compute the node, plus the typical durations of the steps before it over the worker pool; the start is a running run’s latest progress, a queued run’s estimated start, or the next tick of the node’s refresh path plus the schedule’s typical queue wait) andrecheck_at(the next tick that reaches the node). Where a run cannot be promised to leave the node fresh (failing or blocked, undecided, below a staleManual, paused or pinned node, already missed by a tick, a paused run queue) onlyrecheck_atis given, and every surface keeps “fresh” and “rechecked” apart: thebarca statustable addsfresh ~15:05 UTCoroverdue 16hto theWHYof a node that is not fresh, and the web UI’s node panel showsexpected fresh about in 3morrechecked in 3m. A rollup entry gainsfresh_by(the latest estimate underneath) andunbounded(nodes underneath that are not fresh and have none).GET /queueandbarca queue --jsongive each runstarted_at,estimated_start_at(when a run slot is expected to free for a waiting run) andwait_seconds, and thebarca queuetable aSTARTcolumn;GET /scheduleand a node’sscheduleblock givetypical_queue_wait_seconds,typical_run_secondsandqueue_bound(the typical wait exceeds the interval), read from the tick record, so a schedule whose run history was trimmed keeps its typical wait.barca statuson a machine with no server givesstale_sinceonly: no scheduler fires there. Measured on a server with one run slot and two schedules ticking every 10 seconds: estimates were 2 to 4 seconds later than the time each node became fresh. A run’s startup, retries and capacity weights are not modelled. Experimental;barca docs status-fields, “Times”. -
Every node that is not fresh says why, and what explains it; the rollup lists what to do (#963).
barca status --json(and--fields),GET /nodes,GET /stateandbarca.nodes(cause,root_id,root_kind,root_node,gap_seconds) carrycause, one ofcatching_up,queued,no_refresh_path,overdue,failingorundecided(nullexactly for a fresh node),root, the upstream fact that explains the node (sensor_value,code,env,input,never_run,no_schedule,schedule_paused,scheduler_off,failure,queueorundecided, at the node it is about), andgap_seconds, how long the node has been out of date plus how long until it is expected fresh. Roots are found by walking up from a node to the change that started it, so a few of them explain hundreds of nodes: on a 698-node fixture shaped like the audit that prompted this, five roots hold all 422 nodes that are not fresh and the top three hold 392. A rollup entry gainscauses,asset_causesandgap_seconds, androotsinbarca status --rollup --jsonandGET /state/rollupis now every root, ranked, each with the nodes it holds by cause, its gap, how many have no estimate, andaction:{kind, command, estimated_seconds}with kindswait,run,add_schedule,resume_schedule,start_server,fix_failureandraise_max_runs, thebarcacommand that clears the root when one does, and the typical compute time of what it holds.barca statusprints aGap:line (14 overdue · 152 no refresh path · 180 catching up (nodes); about 180 fresh within 5m, 166 with no estimate),barca status --rollupthe ranked roots with what to do about each, andbarca status --jsonhasas_ofandrollup(the scope summed) besidesummary. A--read-onlyserver, andbarca statusbeside a server, read from the tick record whether a scheduler is firing instead of calling every schedule unfired. The web UI’s causes list shows the new roots. Experimental;barca docs status-fields, “Cause”, “Root” and “The rollup”. -
Status names the run queue when ticks wait for a run slot (#973). With one run slot and schedules whose runs overlap, a schedule fired on time while its nodes came up to date late, and nothing said capacity was why. A node on a refresh path whose schedule’s typical queue wait exceeds its interval, or whose newest tick is waiting for a slot, now has
cause: "queued"and the rootqueueat the scheduled node; the root says the wait, the interval and the setting (pulse's ticks wait about 2m for a run slot, every 1m: max_runs is 1) and its action israise_max_runs(more run slots, or spaced schedules). Nothing new is recorded: the wait is the tick record’s.barca docs scheduling, “When ticks wait for a run slot”; what a run costs outside its steps is #951. -
A run list’s words and a file’s health are computed once, for the CLI and the web UI (#959). Each run of
barca history --jsonandGET /runshasline, the run in the words of one row (steps:7 ok · 1 failed · 0 cached;failure:stopped at orders · KeyError: 'region', ordemand_forecast: 7 keys failed · ...for a partitioned node), andGET /runs?status=runninghasnow, the nodes a run is executing, how many wait and the same by group. The rollup (barca status --rollup --json,GET /state/rollup) gainsfiles, each source file’s nodes summed with itsworsthealth, andalso_inon an entry declared in several groups. The web UI prints these instead of working them out: its run list, a run’s “Executing now” and “By group”, the sidebar’s state per file and the file headers of the assets table. A node declared in several groups is now listed where it is counted, with a note naming its other groups, so a group’s list and its count are the same nodes; a file’s state in the sidebar is the most severe health among its nodes. All experimental (barca docs contract). -
Runs in flight and the last day’s activity from the CLI, computed once in barca (#991).
barca history --status runningnow says what each run in progress is working on: anow: executing 3: orders, clean, report · 12 queued · 240/900 keysline under its row andnowin JSON (running,queued,keys,groups,line), the objectGET /runs?status=runningserves, against a server (GET /history?status=running) and for abarca getin progress on this machine (which streams no steps, so every node of its job without a result since it started counts as executing and none as queued).barca history --activity(experimental;--jsonis{activity}) prints the runs started in each of the last 24 hours by status and by trigger, andGET /runsserves the sameactivity: it is one grouped query over the runs of the window, answered from a new index, so the Runs page’s strip covers the whole day instead of the 100 runs it had loaded (the strip’s median duration and the failure text in a bar’s tooltip are gone with the TypeScript that derived them).GET /runs?triggered_by=...filters the list, itstotaland the activity asbarca history --triggered-bydoes, and the Runs page has “Hide schedule runs” (triggered_by=manual,api,client).barca history --servernow prints each run’slineas the server computed it (it recounted the steps without the failed ones). The metadata database gains the indexesidx_runs_startedandidx_runs_trigger, built when an older database is opened. -
barca pause --scheduleandbarca resume --schedulepause and resume one schedule on a server (#989). The web UI could hold one scheduled job back (POST /schedule/{id}/pause,.../resume); the CLI could pause only nodes and the run queue.barca pause --schedule NODE --serverpauses the schedule of a scheduled node untilbarca resume --schedule NODE, or with--untiluntil a duration from now (2h,7d) or an RFC 3339 time has passed;--jsonprints the schedule’sGET /scheduleentry, as the routes answer.?until=of the route takes a duration too.barca pause --jsonandGET /pausesnow also list the paused schedules, underschedules([{id, paused_at, until}]). Experimental (barca docs scheduling, “Pausing one schedule”). -
barca status NODE --keys,--gridand--key KEYshow a partitioned node’s keys (#990).barca statusprinted a partitioned node’s key counts; the keys themselves were only in the web UI’s key explorer.--keyslists every key with its state (failed,blocked,stale,never_run,pinned,fresh), latest attempt, rows, size, run and grouped error, filtered by--stateand bounded by--limit/--all(total,truncated);--gridprints every key’s state, one character each, a row per value of the shorter dimensions, and with--jsonthe documentGET /assets/{name}/partitions/gridanswers;--key KEYshows one key along its chain, its attempts, what it wrote and what it read, and with--jsonwhatGET /assets/{name}/partitions/keyanswers. The same output on this machine and with--server: the decoding of the grid into keys, the state filter and the grid’s rows are computed inbarca-core. Experimental (barca docs partitions, “Listing keys”).
Bug Fixes
- Two runs of a server that start together no longer compute the same asset step twice when it is quick. Runs of one
barca servealready shared an asset step while one of them was executing it (#654). A run that looked for the result before it existed and reached the step just after the other run finished it found no claim and executed it again. It now takes the result the other run finished, when it was already going at that moment; a run that starts later looks in the cache as before. Two ticks that fire in the same second and have a target in common are such runs (#978). - A node that every tick finds up to date no longer reads as undecided or behind (#964).
barca statusand a server’sGET /statepredict what a request would do without running anything, so below a cutoff asset they say would run (for example under a paused node, which ticks read as it is and a request recomputes; below aManualor pinned node status decides as a run does, #985) a node’s state isunknown, however many ticks found it up to date: on a--read-onlyserver such assets readwaitingorbehindfor days while a tick checked them every five minutes. Each status node now carrieslast_check({at, outcome, schedule}: what the newest finished tick that had it as a target did with it, from the tick record), inbarca status --json,GET /nodes,GET /stateand aslast_check_atandlast_check_outcomeinbarca.nodes. A node whose state isunknownand whose last check found it up to date or rebuilt it isokwithhealth_reason: "checked_up_to_date"while that check stands: until the next tick of its schedule is overdue, the node is edited, a newer check fails or does not reach it, or something above it is recorded by another run. The node panel of the web UI and theWHYcolumn ofbarca statusreadchecked 3m ago, up to date. The tick record is read once for the whole scope, and by a server once per change of the metadata database.barca docs status-fields, “Last check”, states the rule and what it does not see; experimental with the rest of health. - A node read while paused is rebuilt after
barca resume(#988). When an input of a paused node changed during the pause (a scheduled sensor above it returned a new value), the ticks that read the node as it was recorded it as proven fresh for the new inputs, and afterbarca resumeevery tick reported it and the nodes below itcacheduntil the input changed again. A run no longer records a freshness proof of a node it reads as it is because of a pause or a pin, andbarca resumeforgets the recorded proofs, so the next tick that reaches the node computes it and theAlwaysnodes below it; nothing is recomputed when nothing changed during the pause. The defect predates 0.44.0 (pauses are new in 0.41).barca unpinandPOST /schedule/{id}/resumewere not affected: a pin already forgot the proofs, and a paused schedule runs no tick. - Rough edges in the web UI (#970). A node’s panel no longer reads
success · in 20774dwhile its group’s state loads: a time is never measured from anowthat is not known yet (it is read against the clock), and a zero or absent time is a dash. The Last success column is drawn with its rows when their state is already known, and otherwise holds its place with a skeleton instead of painting blank. The grouped page’s header no longer cuts its breadcrumb, contents (399 assets · 49 tasks) and health summary to fit one line: only the crumbs between the root and the heading are shortened (whole in their tooltip), and the view switch wraps to a second line when the rest does not fit. - One definition of a late schedule (#958). An every-minute schedule on a busy server could read “late by 2m” on the Assets page, “last run 10h ago” and not late on the Schedules page, and “just now” on the Runs page, because each was derived separately: lateness from the
runstable, which has no row for a tick whose run still waits in the run queue; the last run from the scheduled node’s own last result, which a tick that finds the node up to date does not write; and the grace in two places in the web UI. One function (barca_core::schedule_standing::standing) now decides a schedule’s last tick, the run it started, its next slot and whether it is late, from the run queue and the runs the schedule started, andGET /schedule, thescheduleblock ofGET /stateand ofbarca status --json(GET /nodes) and the web UI all read it. A schedule is late when a slot after its newest tick passed longer ago than its grace (60 seconds, or half the interval below two minutes) plus its queue wait (the median of its newest 20 runs or, when longer, its newest tick’s own), so a tick waiting for a run slot is not late. New keys:late,late_sinceandlast_run_idonGET /scheduleentries and in thescheduleblock, whichGET /staterows now carry; the Schedules page shows the last tick and its run’s status and sorts late schedules first. Changed:last_statususes the run list’s words on every surface (successwhereGET /schedulesaidcomplete,pendingfor a queued run) and is filled without a running scheduler;last_firedis the newest tick a run was started or queued for,nulluntil there is one (GET /scheduleused to report the server’s first start for a schedule that never fired). barca get --dry-runno longer calls an asset pinned withbarca pinunknownwhen it reads a sensor (#985). A run does not plan anything above a pinned asset, so the dry run found no recorded output for the sensor it reads and reported the asset and everything below itunknown(sensor_output_unknown), where the run serves them from cache. The dry run now sayscached, as the run does.
Documentation
- Health, causes and the freshness gap are specified (#953).
specs/behavior/health.md(implemented in this release; each section has an “As implemented” note where the code differs from the intent) fixes what the series builds: the health words and how each follows from a node’s state, one cause for every node that is not fresh (catching up, queued, no refresh path, overdue, failing, undecided) with the upstream change or missing schedule behind it, the refresh path,stale_since,expected_fresh_atversusrecheck_at, the freshness gap, the rollup (GET /state/rollup,barca status --rollup), what a tick records, thebarca.schedules,barca.ticksandbarca.queuetables and a read-onlyPOST /sql/queryoverbarca.*tables. DIRECTION.md’s UI decision is amended: health words are barca vocabulary defined once in Rust and shown by the CLI and the UI alike, in four layers (records, classification, aggregation, presentation). - The web UI’s layering is checked on every pull request (#959). The UI and the CLI only render: every derived answer is computed in
barca-core.scripts/check-ui-layering.py(a prek hook, so it runs in every CI tier and inscripts/check-fast.sh) fails when the UI calls a server route that is not mapped to the CLI command printing the same answer, when a module ofui/src/libhas no declared kind (fetch, types, display, format, layout, page), or when a health or cache-state word is compared or produced in TypeScript outside a display module;cargo test -p barca ui_layeringholds the same table (crates/barca-cli/ui-layering.json) to the real CLI and the server’s router, and the UI’s test fixtures take their health words fromhealth::classify. What is still derived in TypeScript is listed there by name with the issue that removes it (#932, #962, #989 to #992). How to extend the table:contributing/ui-layeringon the site.
0.43.1 (2026-11-17)
Bug Fixes
- The health map reads like a disk map, and healthy assets are green. A segment’s size is now how many assets are under it (a partitioned asset counts once; tasks and sensors colour their group but take no room), matching the page’s asset counts, so the map is the project’s shape: groups keep the worst health inside, and members too thin to draw one by one become bands sized by the assets inside them in each colour, so mostly healthy groups read mostly green instead of all yellow. Zoom in and a partitioned asset shows its keys in a ring outside it (failed, not up to date, ok), with a few failed keys among thousands still visible. The map is drawn as flat pastel segments parted by hairline gaps, rings that thin outward up to six levels deep, and one number at the centre (how many are in the worst health, as the page header counts them); the line under it names the segment under the pointer, whose branch lights up while the rest dims.
0.43.0 (2026-11-17)
Features
- The web UI shows what is wrong, and where (#925). The Assets page opens on a health map of the open scope (project, group or file) beside its causes. The map’s slices are sized by how much is wrong under them (failed keys of a partitioned asset, otherwise nodes) and coloured by the worst health inside (red failing, yellow needs attention, green ok); clicking one opens it, and the whole page follows. Causes list what is wrong once per cause, biggest first: failures that share an error are one entry, with their failed keys and the nodes they keep from running. Every count for a scope (the page header, group rows and panels, group cards on the graph, the map) now counts one health per node, so they agree:
failing,blocked,suspect data,behind,waiting,never runorok. A node keeps its precise state;unknownreadswaiting, and a node waiting on a cutoff below a failure readsblocked. - barca records row counts and raises data signals. Every successful tabular result records its row count (pandas, polars and pyarrow frames in any format; polars lazy frames and DuckDB relations written to parquet; each key of a batched call):
materializations.rows,last_materialization.rowsandpartitions.emptyinstatus --json,rowsinhistory RUN_ID --json,stats --jsonandbarca sql.GET /statereports, from those facts only,signalsper node:empty(it wrote 0 rows; for a partitioned asset, how many keys did),rows_changed(more than half up or down against its previous result) andbehind_input(a node barca cannot decide on whose input has a newer result). The UI shows them assuspect dataandbehind, in the causes list and the node’s panel, with each run’s rows in its history. - A run explains itself. A run records why it executed what it did, aggregated by reason as it plans (never run, code or an input changed and which, new partition keys, a forced refresh, a retry of a failure, an evicted result), who asked for it (
principal: an API token’s name) and an optionalreasongiven toPOST /runs, and why it was cancelled (cancellation: by whom, whether it had started, which runs it waited behind and which did the same work).GET /runs/{id}andbarca history --jsoncarryplan_reasons,principal,trigger_reason,retriesandcancellation(experimental), andGET /runs/{id}pages its steps (?offset=) and shows a live run’s newest log lines. The run panel opens with a Run overview: why, who, attempts and retries, and for a live run its progress, what executes now, by group, and an estimate of what is left. - Schedules say when they are late.
GET /statereportsprev_runandlate_since(the first cron slot no run has started for); the Schedules page showslate by 12minstead of counting down to a slot the schedule will miss, and puts late schedules first. - The web UI’s queue is visible everywhere: while runs wait, the sidebar shows how many run and wait and the oldest wait, linking to the Runs page.
- The sidebar can be resized by dragging its edge or with the arrow keys on it (the width is remembered), lists no file with nothing of the page’s kind, and shows one project state when collapsed.
Bug Fixes
- A large run opens at once. A run’s logs and steps rendered every line (a run of 30,000 log lines and 5,000 keys built 167,000 elements and stalled the tab); they now render what is in view, and a node’s keys are one row until opened.
- The Runs page keeps its history in view. A long queue took the whole page and left the run history and the run’s panel a 50-pixel strip. The queue scrolls inside a bounded strip and folds to one line, the run panel has the page’s full height, and the filters visibly change the list. The queue lists the running run first, with how long it has run, and a filtered count over the runs loaded says it is partial (“21 not successful in the latest 100”).
- The graph is readable at any size. A fit never zooms below the size where a card’s smallest text is 11 px (it centres on the selected, failing or running node and the rest is a pan away), edges no longer cross cards, cards keep their last known state while a scope loads instead of showing “Checking…”, the top level shows the same groups as the list with the edges between them, opening a node’s panel pans the graph to keep the node in view, and a group card leads with its failures.
- Counts agree across the UI. A failing streak reads “N failed runs in a row” and a total “N runs recorded”; a partitioned asset’s last success says it is any key’s; a run requeued onto new code no longer counts a key twice in a node’s history, its
last_runor the run’s node summary; group rows count all their failing members; the page header counts assets, tasks and sensors and the groups they are in. - A read-only server reads as one.
GET /healthon a--read-onlyserver reports the queue the metadata DB records, asGET /queuedoes (it said 0 queued while 19 waited). The UI says read-only once, across the top, and shows no write buttons instead of dozens of disabled ones; the Schedules page says that schedules fire on the server that owns the scheduler. - Tasks and sensors show how their last run went (
succeeded,failingornever run) instead ofalways runson every row, and the Tasks page opens unfiltered, as its filter says. - One time format: every time in the UI is relative (
3m ago,in 5m) with the exact time on hover; no timestamp is cut off. - The node panel leads with what matters: a partitioned asset’s keys (total, cached, wrote 0 rows, rebuilt and failed in the last run), then the error, then a folded summary of what changed (
code, 2 inputs, 15 helpers); History folds identical consecutive failures into one line; the Data tab names the key it shows and why. - The command palette shows each result’s state, failing first; the Assets search lists matching members with their path instead of their ancestor groups; rows no longer move under the pointer while states load; pages have their own titles; a page that fails to render shows its error inside the app instead of a blank developer screen; the tables fit at a laptop’s width without scrolling sideways.
Performance
- The UI polls less:
/stateand the runs list refresh every 10 s when nothing runs (every 2 s while a run is live) and not at all in a hidden tab.
Documentation
- The Web UI page describes the health map, the causes list and the health words, why a run ran, the queue in the sidebar and the read-only view.
barca docs status-fieldsgains Row counts,barca docs server-modeData health andbarca docs schedulingA schedule that missed its slot.
0.42.1 (2026-11-14)
- Internal: barca-core split into barca-model, barca-compile, barca-db and barca-engine crates; no behavior change.
- UI-only PRs and merge groups run UI checks and browser tests without unrelated backend suites; releases keep full coverage.
Performance
barca serveread routes stay fast while runs write results. Every read route used to recompute from the whole history each time the metadata DB changed, which on a busy server is several times a second. On a copy of a real project’s database (470k results, 645 nodes) with results written at its production rate and a run in flight,GET /statetook 2.4 s and the asset, schema, partition grid andGET /nodesroutes 0.5 to 1 s each; they now take 60 to 120 ms (p95), andGET /sql/views70 ms instead of 1.5 s. Node ages, last materializations and typical durations are kept between reads and updated from the rows added since (rows deleted bybarca gcor a reset make them be read in full again), and they share one count of the table while the database files are unchanged.GET /historywithout a limit (every run, 17k on that copy, 51 MB) writes each run straight to JSON, the same bytes, in 255 ms instead of 370. A dry run asks only about the missing results whether they were evicted instead of reading every evicted path, failed keys are read fromidx_mat_failed, andGET /sql/viewsno longer re-parses the pipeline on each call. A new index,idx_mat_run_node (run_id, node_id), is built when a database is first opened, under half a second for 470k rows.benchmarks/read_routes/under_writes.pymeasures every read route under that load.
Bug Fixes
- A requested run goes ahead of scheduled work on
barca serve. A run asked for over the API, the UI or a--serverclient starts before waiting scheduled runs, and when every--max-runsslot is held while a scheduled run executes, it takes one extra slot of its own instead of waiting.GET /queuepositions follow the new order. - A run’s progress no longer reads past 100%.
steps_totalcounted a dynamicpartitions_fromstep as one step, from the plan, whilesteps_executedcounted each of its keys (one run showed 2,560 of 316). The total is raised to the expanded count once keys are known, and never stays below executed plus cached steps. - A blank
BARCA_SERVER_TOKENcounts as unset for the CLI and the PythonClient, instead of failing every server command with exit 2. Containers and.envfiles that exportBARCA_SERVER_TOKEN=for an unauthenticated server work without unsetting it.
Documentation
- barca.sh deploys from main: a merge that changes the site is live a few minutes later instead of at the next release, and a pull request that changes it gets a preview link in a comment (
.github/workflows/site.yml; the release workflow no longer deploys the site). CI runs no clippy, wheel build, Python tests or performance tests for a change only to the site. - New manual topics, split out of the longest ones:
barca docs hashing(which code and decorator arguments a run hash follows),barca docs refresh(--refresh,--refresh-all,--no-cascade,Manualupstreams,--dry-run),barca docs external-data(data that changes in place, and@asset(cutoff=True)),barca docs artifacts(what a run reports per step, and a cached result whose file is gone) andbarca docs slack.barca docs cacheopens with an “At a glance” table of what runs again after each kind of change,barca docs server-modewith what one server does for a team, andbarca docs statuswith its output. Topics open with what they are for, and Disk Use and Metadata Backups have section headings. - barca.sh is organized by task. The sidebar groups pages as Start Here, Why Barca and How It Works, Writing Pipelines, Running and Caching, Commands (by Run, Inspect, Manage, Server), Servers: Guides, Servers: Reference, Storage and Configuration, Automation and Agents, Recipes, Worked Examples and Project. Every command has a page at
/reference/cli/<command>/titledbarca <command>; recipes are at/recipes/and worked examples at/examples/under readable names. Every old address redirects (301). - New pages on barca.sh: Why Did (or Didn’t) It Run? (
/troubleshooting/), Server Overview (/serve/, which server page answers which question), Authentication and Tokens (/auth/), The Web UI (/web-ui/), Release Notes (/releases/, the top bar’s Changelog link) and All Pages (/all-pages/, A to Z). - barca.sh’s homepage says who barca is for and shows it working: a two-asset pipeline and its two runs (the second runs 0 steps), measured numbers against Dagster, and where to go next. It has a menu on phones. Three diagrams show a run from parse to record (Architecture), partitions fanning out and collected (Guide) and a team setup (Share Results With a Team).
- Search on barca.sh puts the page that answers a question first, including whole-sentence questions (“asset didn’t rerun after csv changed”), suggests fewer words when nothing matches, and ranks contributor pages and RFCs last.
- The Web UI page shows the UI: screenshots of the Assets view, a failed run’s panel and a partitioned asset’s panel, with the button names as the UI shows them. Server API opens with a quick start (start a run with
curl, follow it, read the result) and a table of where to look; Decorators API opens with a table of every name and what it is for; Remote Storage andbarca docs statusopen with where to find what. - barca.sh navigation: previous and next links stay within a sidebar section, the Commands section groups its commands (Run, Inspect, Manage, Server), Web UI screenshots are cropped to what the text describes, and the Release Notes search index skips unreleased notes.
- Server API is two pages: Server API (a
curlquick start, runs, the Python client, errors) and Server API Endpoints (every route, inspection, the run queue, scheduling, limits). The Web UI’s states table says what each state means, the Slack page says it is the only built-in alert, Server Mode points to the three-step setup, and search answers “environment variables”, “clear cache”, “exit code 3” and “run from python”. - Shorter pages: Getting Started ends after changing the code, with a short list of what else barca does;
barca docs status-fields(site page barca status: Fields and JSON) takes each node’s fields, the JSON document and the fine print out ofbarca docs status; Helpers API takespartitions,collect,asset_ref,@sink,paralleland the other exports out of Decorators API. - Release Notes opens with Highlights: a few sentences per recent release in a user’s words, with what is breaking, above every version’s full notes; the release steps say to update it.
- Exit Codes and Errors (
/reference/cli/exit-codes/) is a page of its own, the server pages are one Servers group with its reference pages nested, and search answers “schedule a job daily” and “run every hour” with Scheduling With Cron. - Barca vs Cron and systemd Timers re-checked on 0.42.0:
barca listoutput, catch-up after downtime, overlap skipping and retries were run on that release, and the page no longer carries a “not re-checked” warning. - Easier reading on barca.sh. Cross-references are titled by the page and section they open (The Cache: Environment variables) instead of the terminal command. Terminal output keeps its columns on a phone, and long commands wrap under their first line. Barca vs Dagster and Barca vs Prefect open with a concept map and a “Choose Dagster/Prefect when” section.
- barca.sh checked against barca 0.42.0. An audit ran the site’s examples and compared its claims with the code:
barca serveis documented with its opt-in tokens, queued runs as resuming after a restart, and the Server API without a run time limit it does not have; the configuration example parses; flags, output samples,/healthandPOST /runsfields, the architecture’s database (libSQL), Datadog’s one trace per step, RFC statuses and the worked examples’ claims match 0.42.0.
0.42.0 (2026-11-09)
Features
-
Cancel queued or active runs from their inspector, with confirmation and cancellation progress. Incomplete runs no longer claim unrecorded steps were cached or successful. Resume a paused pipeline directly from its Incident controls, with the affected file and count confirmed before resuming. Pauses in other pipelines remain in place.
-
Retry exactly the partition keys shown or grouped under one issue, including scattered multi-dimensional combinations.
--partitionalso accepts a JSON array of exact key objects; queued runs retain that scope across restarts. -
Repair individual partition keys: upload replacement data or pin an earlier version from the key inspector or
barca pin 'asset[dimension=value]'. Pins hold only the named key through refresh, identify held keys in the explorer, and show the held version in previews. Confirmations accept a repair reason. Unpinning restores normal computation. -
Web UI: calmer, less crowded layout. Four type sizes (12/13/15/20px, 13 body) with weight for hierarchy and sentence-case column headers. Each page has one toolbar row (title and count, the state filter, search, the last-run filter, the List/Graph switch and Run); the “1 failing · blocks N downstream” banner is gone (the failing filter’s tooltip says what it blocks). Asset, task and sensor rows are one 36px line under a foldable header per source file (its count and worst state); the path under each name is gone (the id is in the tooltip), Last run and Last success are one cell (
17m ago,failed 17m ago · last ok 2d ago), Next run shows only when a node has a schedule and Typical only when a node takes 0.1s or more. The top bar no longer has a Run button: the page toolbar runs what is open (Run all,Run billing.py, the count in its tooltip), the node panel or graph inspector runs its node, and Ctrl/Cmd-K offers both. The side panel is 400px with plain sections instead of cards, a one-line title and id with the copy button inline, and a failure’s error shown once (the asset panel’s Last attempt and History, and the run panel’s Run and Steps sections, no longer repeat it). Runs, Tasks, Sensors and Schedules follow the same rules. -
Web UI: one navigation, in the sidebar. The top tab bar and top bar are gone: the sidebar holds Search (Ctrl/Cmd-K), then Assets, Runs, Schedules, Tasks and Sensors with icons and muted counts (the open one on a neutral fill, runs in progress beside Runs), then the pipelines, then Docs, the connection, the time zone and the theme; collapsed, it keeps every icon. Each page’s toolbar is its first line. A pipeline’s count and glyph in the sidebar are now derived exactly as its file’s header in the table (they could disagree, e.g. a file counting its tasks and sensors and showing a failed task’s red glyph on Assets) and are of the open page’s kind, labelled (
assets,tasks,sensors). The asset search no longer takes focus on load. The graph fits the whole pipeline with 48px of room when it fits at 0.8 zoom or more, cards are one line (glyph, name, a task’s or sensor’s kind; the state’s word is in the tooltip), edges are a neutral hairline that the selected or hovered node’s edges strengthen, and the legend lists only the states on screen. Runs shows the last 24 hours as a full-width hourly chart with a one-line summary, and a run’s facts are a two-column grid without a second status badge. Empty Tasks, Sensors, Schedules and Runs pages say what the kind is and how to add one; light-theme hairlines are 5/8/13% ink like the dark theme’s. -
Web UI: one toolbar for List and Graph, and quieter panels. The graph view has the list’s toolbar (count, state filter, search, last-run filter): a node the filter leaves out is dimmed, not removed. Zoom, fit and the layout direction are one row of controls at the canvas’s bottom right, and a graph smaller than the canvas is placed a little above the middle instead of leaving a band of empty space over it. Run all is gone from pages with nothing of their kind (no tasks, sensors, schedules or assets). The run panel’s actions are one row: Re-run failed (the failed steps and what is downstream of them; its tooltip says so), Re-run all, and copy incident summary as an icon; the log tools’ Copy and Download are icons too, so they stay on one line. Node and step names are sans everywhere; mono is kept for run ids, hashes, file:line, code and logs. The asset panel and the graph inspector share one header (the name, its kind in muted words, the id muted with its copy button, Run), and sections with nothing to say collapse: no duration histogram placeholder before two successful runs, no chart or p95 for a single run, one line for a source node’s inputs and for an empty blast radius, no Consumers section when nothing reads the node, Refresh and Upload replacement… at the right of their section’s title. Every toolbar control is 28px, so the title sits on the same line on every page.
-
Web UI: one control style in the asset panel. Incident controls are one row of the same quiet button (the confirmation still warns), and say
pausedonly when the asset is; links inside text (open the run, All paused assets…) have a faint underline so they read as links; a version showslatest,pinned,evictedoruploadedas a small tag beside its hash and its details on one line, cut short rather than wrapped; the Consumers section is gone (Blast radius lists everything downstream; the direct readers are under Technical details); the state’s explanation starts with a capital; and the time filter’s chevron matches the other controls. -
Every key of a partitioned asset in one request (experimental,
barca docs server-mode):GET /assets/{name}/partitions/gridanswers with the dimensions and their values and, for every key, its state asbarca statusdecides it (fresh, stale, never run, failed, or blocked behind the same key of a failed input) and its latest attempt’s time, duration, size, run and error, in compact columns (about 230 KB for 10,000 keys, computed in under half a second and kept until the database changes). It decides the state across the asset’s chain, the partitioned assets it shares its keys with, so the 83 keys of a 10,000-key downstream asset that wait on 83 failed keys read as blocked and the other 9,917 as fresh.GET /assets/{name}/partitions/key?key=answers with one key’s state in each asset of the chain, its latest attempts, and the schema and first rows of its result and of the same key of each input. Failed keys’ errors are grouped with each key value replaced by its dimension’s name (s3://raw/<region>/<day>.csv), only where it is a whole word. -
Web UI: a key explorer for partitioned assets (
#/keys?node=<asset>,barca docs partitions, “Exploring keys in the web UI”). Every key at once on a canvas, coloured by state, one block per value of the shorter dimension with each row’s first value beside it (a day × region asset of 10,000 keys is four blocks of 2,500 days, and a bad week in one region is a red streak); filters by state, dimension value, error group and key text over a virtualized table of the keys they keep; one key’s detail with its error, attempts, the schema and first rows of its result and of the same key of each input, and its state in every asset of its chain; and Run for the keys that are not fresh, of the values selected or of a Shift-click range. The asset panel links to it, its grouped errors open it filtered, and an asset list row says6 of 360 keys failedwhere it said onlyfailing, and83 of 10,000 keys wait on account_scoreswhere it said onlyblocked. ⌘K’s key results open the explorer at the key. A partitioned asset’s panel no longer says “No successful run yet” and “No successful materialization” when thousands of its keys succeeded, and the toolbar has oneblockedchip where it could show two. -
Web UI: partitioned runs and graphs at a glance. A run’s failed keys of one asset that failed the same way are one line in its summary (
account_scores · 83 keys · open in the key explorer, with their error) where it listed five of them and “and 78 more below”. A partitioned asset’s graph node says how many keys it has (10k keys) and draws a thin bar of the share failed and waiting to run, with the counts on hover. -
Web UI: the key explorer says what is wrong first, and never scrolls. It reads top down: the keys counted by state; one line per problem (each error of the failed keys, then blocked, stale and never-run keys) with how many keys and where they are (
day 2023-03-01 → 2023-03-20 · region apac), Show and Run; an overview of every key in a few rows of columns that fit the page, fresh quiet and problems loud, that zooms to a stretch you drag across; then the keys that need attention (or all) in a table that scrolls on its own. A key’s detail leads with its error, then the key along its chain and what it read. The asset panel is in tabs (Overview, Data, History, Incident) under its state, so it fits a window; its Keys section names the failed keys’ errors and links to the explorer instead of listing keys 100 at a time.
Bug Fixes
-
Recovery actions together: replacement upload and version pinning now live in the asset’s Incident tab beside pause/resume. The summary links to pin review instead of unpinning without confirmation.
-
Readable grouped tables and explicit graph fit: mixed group/node tables preserve column widths and scroll instead of overlapping values. Fit to screen shows every graph node, including on laptop windows, and a delayed automatic fit no longer overrides the operator’s view.
-
Partition recovery feedback: the key explorer’s primary run follows its visible filters without widening an inexact selection; completed retries report their outcome and refresh the open key. Retained results on failed or stale keys are labeled as the last successful output.
-
Web UI: the graph fits once its nodes are measured and re-fits when the canvas changes size until you pan or zoom; switching from List to Graph could leave it unfitted at the canvas’s top-left corner.
Documentation
- barca.sh: attach the Worker custom domains in
site/wrangler.jsoncand build the site in CI’s fast tier so docs deploy fixes are validated without touching the release workflow.
0.41.0 (2026-11-08)
Breaking
- Web UI: a node’s state reads
freshwhere it readcached, and a node whose last attempt failed isfailingeverywhere, never alsonever runorcached; the state filters follow (astate=never_rundeep link no longer lists failing nodes, which have their own filter). The CLI and JSON keep theCacheStatevalues.
Features
- Pin an asset to an earlier materialization for crisis data fixes (experimental,
barca docs pins):barca pin <asset> --previous/--run-hash <h>(with--versionsto choose and--reason),barca unpin <asset>, andbarca pinto list pins. While pinned, every run (downstream steps,barca get,barca.get(),--serverruns, scheduled ticks) reads the pinned result as step reasonpinnedand none recomputes the asset, not even--refresh; the result is never evicted. The pin, with when, who and why, is a newasset_pinstable in the metadata database.barca serveaddsGET /pins,GET /assets/{name}/versions,POSTandDELETE /assets/{name}/pin(OpenAPI specification 19), and the asset panel of the web UI a Versions list with “Roll back to this” and a pinned banner with “Unpin”, each behind a confirmation. Only unpartitioned assets; uploading a file as the pinned value is not supported yet. - The Runs page is a debugging and recovery surface. A run’s panel opens with what failed (each failed step, its error and where it raised) and its actions: “Re-run failed steps + downstream” (the same target cache-aware: steps that succeeded are cached), “Re-run whole run” (
refresh_all), “Retry” on each failed step or partition key, and “Copy incident summary” (markdown with the run’s link, target, trigger, timing and failed steps). The new run is selected at once. The logs filter by step (a step’s “Logs” button or its name on a line), by text with matches highlighted, and to errors only; “First error” jumps to it, and the lines shown copy or download. All through the existingPOST /runsandGET /runs/{run_id}; no API change. - Web UI: one state per node, in plain words. A node whose last attempt failed is
failing(red, with “last good 3h ago” or “never succeeded”); otherwisefresh,stale,never runand the other cache states, never a snake_case enum; filters and header counts use the same states, and every state badge has an icon beside its colour. Assets gets a failing summary (“1 failing · blocks 2 downstream nodes”) and tinted failing rows; the asset and run tables no longer scroll sideways (low-priority columns leave as the table narrows; “Typical” is now “Typical duration”), and an inline error opens the side panel instead of expanding in the row. Errors read in the sans font with the traceback below in mono, its paths relative to the project root and wrapping at/. The Run button is on every tab, the connection readsConnected, Search has a visible label, counts are pluralized (1 run), the run panel’s markup is valid HTML, and the light theme’s faint text meets WCAG AA contrast. GET /assets/{name}hasfailurewhen the node’s latest execution failed:raised_at(the last traceback frame inside the project, relative to its root), the failed attempt’srun_hashandrun_id, andlast_success(nullwhen it never succeeded). The asset panel’s “Why it failed” box shows “raised at assets.py:136” beside the definition line (now labeled “defined at”) and what changed since the last success, by run hash: the components that moved, the same run hash as the last success (the cause is outside the definition), or that the code moved on after the attempt.- Contain an incident from the asset you are looking at.
barca pause <target> --server(a node,--downstreamfor everything below it, or afile.pyfor every node of it) andbarca resume <target>/barca resume --all, alsoGET /pauses,POST /pausesandPOST /pauses/resume, hold assets back from scheduled and sensor-driven ticks until resumed: a paused target is a skipped step with reasonpaused(its detail namesbarca resume), and a paused node upstream of a tick’s target is read as it is. Pauses are kept in the metadata DB (asset_pauses) across restarts. A run by hand that names a paused node needs--allow-paused(allow_pausedinPOST /runs, a confirmation in the web UI). The web UI’s asset panel gains a Blast radius section (every downstream node, and the schedules that compute the asset or what reads it, with their next run) and Incident controls (pause the asset and downstream, its pipeline file, the related schedules and the run queue, and resume each, destructive ones behind a confirmation); the assets list labels paused assets and a banner says how many are paused, linking to them (?paused=1). Experimental;barca docs incidents. - Web UI: a node a failing node upstream keeps from running reads
blocked(amber, with a barred-circle icon) instead ofnever runorstale, with “by broken_report” linking to the failure, in the Assets list, the asset panel and the graph. The Assets header has ablockedchip (?blocked=1), and “blocks N downstream nodes” counts exactly those rows. Derived in the UI from the graph; the API is unchanged. - Pin an asset to data you supply (experimental,
barca docs pins):barca pin <asset> --from-file <path> [--reason ...](also--server) loads a.json,.parquet,.csvor.pklfile with the reader runs use, stores it as a new artifact of the asset with a content-derived run hash, records it as a materialization marked as an upload (a newasset_uploadstable: when, who, file name, reason) and pins it, with the semantics of any pin untilbarca unpin.barca serveaddsPOST /assets/{name}/pin/upload(the file as the body,?file_name=/?format=/?reason=, at most 256 MiB,403read-only); versions gain anuploadkey; the asset panel’s Versions section offers “Upload replacement…” behind a confirmation naming the file and size, and the pinned banner names who uploaded the override. Only unpartitioned assets. - Web UI: a pinned asset reads
pinned(warning tone, pin icon) instead ofstale, with “override from fix.json” or “rolled back to” and who pinned it, in the Assets list, the asset panel (“Pinned: runs read this version until it is unpinned”, with Unpin) and the graph; it outranks every state but failing, and a failure above it no longer marks what reads itblocked. The Assets header has apinnedchip (?pinned=1) and every page a banner “N assets pinned · runs read pinned versions” linking to them.GET /pins(andbarca pin --json) entries gainrun_idandupload. - View a step’s Datadog trace from the Runs page. A run traced with
BARCA_TELEMETRY=datadogis recorded as traced (runs.trace), and each step that ran or failed getstrace_id(128-bit, 32 hex digits) andspan_idinbarca history RUN_ID --jsonandGET /runs/{run_id}, derived from the run and step as the trace was, so nothing changes in the worker protocol.GET /projectnames the Datadog web app intelemetry.datadog_url, fromDD_SITE, else the new[telemetry] datadog_siteinbarca.toml, elsedatadoghq.comwhen the integration is on. The run panel shows “View trace” on each step row and failed step, and “Copy incident summary” links each failed step’s trace; both are hidden without a site or a trace id. Experimental;barca docs telemetry. - Web UI: a calm, neutral palette; colour only on a state’s glyph. Both themes move to true neutral greys (the dark theme loses its green cast, the light theme its grey-green), with hairline borders and one muted indigo accent for focus and pinned assets. Every state is drawn by one 14px
StatusGlyph, its own shape and a desaturated hue tuned per theme (failing a red cross, running a turning blue arc, fresh a green check, stale amber half-filled, blocked an orange barred ring, partial violet, unsynced teal, pinned indigo; never run, unknown, always runs, paused, queued, cancelled and skipped in grey), with its plain word beside it in the text colour. The glyph replaces the coloured pills, dots and icons in the Assets list, its header filters (now one neutral segmented control), the asset panel, the graph (whose nodes lose their coloured edge bar, duplicate dot and per-node kind icon), its legend (now telling blocked, stale, partial and unsynced apart), the Runs list and run panel, the Tasks, Sensors, Schedules and grouped pages and the sidebar. Failing rows are no longer tinted or barred, the failing summary and the error boxes are neutral, and error text reads in the text colour; a failure is found by its glyph and the default sort. Every text colour and state hue holds WCAG AA contrast (4.5:1) on every background of both themes, whichtokens.test.tsnow checks.
Bug Fixes
- Web UI: a failed run’s step count no longer reads “8 ran · 0 cached”: the runs list and run panel say “7 ok · 1 failed · 0 cached” (and the skipped nodes, in the run panel).
barca get --json’ssteps_executedis unchanged (it counts executed steps, failed ones included, as the manual now says). - Web UI: the asset panel’s History for a node whose every attempt failed says so (“No successful run yet”) and lists the attempts with their errors, instead of empty duration tiles and a full-height placeholder bar.
- Web UI: the asset panel’s Blast radius names each downstream node’s state in the assets list’s words (
blocked,pinned,failing), not its raw cache state (never run). - Web UI: the copied incident summary links to the run through the UI’s hash route (
…/ui/#/runs?run=<id>); the link it gave before opened the Assets page.
0.40.0 (2026-11-05)
Breaking
- Datadog: a step execution is the unit of a trace, not the run (#845). Every step that ran or failed is a trace of its own, rooted at
barca.step(resource the asset’s short name, the partition key inbarca.partitionandbarca.node_id), with the worker’sbarca.executeand library spans inside it; the run is a separate one-spanbarca.runtrace, and a run’s traces sharebarca.run_id. Gone with the run-shaped trace: thebarca.partitionoperation (a key is abarca.stepof its own), thebarca.partitions.*metrics and the 200-keys-per-node / 2,000-per-run caps (every key has a trace), thebarca.cachedtag and the zero-length spans of cached and skipped steps (they send nothing;barca.steps.cachedand.skippedon the run span count them), and the per-node summing ofbarca.bytes,barca.cpu_secondsandbarca.max_rss_bytes. Monitors and trace metrics onbarca.stepperresourceand onbarca.runkeep working;barca.attemptsis now on every step that ran or failed, keys included.BARCA_LOG=jsonlines about a step carry the step trace’s ids.
Features
- Datadog: a step’s trace is sent the moment the step ends, in the background, instead of the whole run’s at the end: a failure is in Datadog seconds after it happens, a run that is killed has sent every step that finished, and the coordinator holds no spans across the run. The run’s trace goes at the end as before, and sends any step the live path could not. A delivery warning names what was not received (
did not receive step pipeline.py:orders); it is still printed once per failure streak.
0.39.6 (2026-11-05)
Features
- The Python stubs are typed:
asset,sensor,taskandsinkhave overloads for bare and parameterized use,parallel,parallel_map,collectandGroupcarry parameter and return types, so an IDE completes and checks decorator arguments without importing barca’s runtime.
Documentation
- The manual’s long topics are split, each new topic with its own page on the site:
barca docs disk(the size limit and eviction, fromcache),barca docs layout(the project root,.barca/, concurrent and killed runs, upgrading, fromcache),barca docs backup(metadata backups and restore, fromremoteandserver-mode),barca docs serve-ops(the run queue, stopping, restarting, stop grace, shared capacity, run timeout, fromscheduling) andbarca docs batched-partitions(batch=, frompartitions).barca docs agentspoints at the contract for the output envelope instead of repeating it. - One owner per table: the exit codes are the generated table in
barca docs contract(agents, the skill, the README and the site CLI page point there); the cache states and reasons arebarca docs status(the site CLI page saidunsyncedhad one reason andunknownone; both have four); the.barca/entries arespecs/interfaces/dot-barca-layout.md(the manual and the configuration page had drifted: no lock files, no.csv, “SQLite” for libSQL). The experimental list inbarca docs contractand the README’s command table are generated from the CLI definition andEXPERIMENTAL, so they can no longer disagree with the stability column (they did: tokens,history RUN_IDand its filters,--reconcile,list --groups,get/run --batchwere missing, and the README calledstate backupsandrestoreexperimental). - The site mirrors the manual topics
agents,assets,cache,logs,partitions,sinks,status,tasksandtypesas generated pages with an edit link, like the pages it already generated; the development page describes the worktree and fast-profile workflow,scripts/check-fast.shand the merge queue. The server API page says howLast-Event-IDresume works (shipped in 0.36.0) instead of calling it future work. DIRECTION.md records 0.39.5 as shipped and the 0.39.6 cleanup list; its drain note gives the exit codes the server has (0 after the timeout requeues runs, 1 only when a second signal cancels them). The specifications say the sequential historical-selection fix shipped (0.34.0) and that a server’s shared in-flight steps pass their conformance scenario, close out the architecture plan with what shipped where, and record theCacheStateenum as the one spelling of a node’s state. GLOSSARY.md gains the user vocabulary (the eight states, run hash, ledger, store, environment, cutoff, node, step, attempt, batch). - CI’s fast tier now runs the prek hooks on every pull request (ruff and ruff format at their pinned release, ty,
cargo fmt --check, the version sync anduv lock --check), the same hooksscripts/check-fast.shruns locally; the pins move to ruff 0.14.14 and ty 0.0.97, also pinned in pyproject.toml’sdevdependency group. The release process refreshesscripts/ci-test-durations.jsonfrom the full tier’s measurements (scripts/release.sh, thedurationsjob), Dependabot proposes weekly grouped updates for Cargo, uv, the two npm trees and the actions, andscripts/new-worktree.sh --linkercopies the trunk’s linker settings into a new tree.tests/README.mddescribes the shell integration and simulation suites.
Bug Fixes
- The server’s
GET /runs/{run_id}/outputreads a final artifact’s format from the same extension table as the worker andbarca sql(crates/barca-core/src/artifact_format.rs, mirrored frombarca._artifacts.FORMAT_OF_EXTENSIONby a test): it took every extension other than.json,.parquetand.csvfor pickle, wherebarca sqlreportsunknown. TheContent-Typeit serves is unchanged (pickle and unknown are bothapplication/octet-stream); the two tables can no longer disagree. - UI: every node state is one of the eight words
barca status --jsonprints (cached,stale,unsynced,blocked,never_run,partial,always_runs,unknown), shown as the server says it with itsreasonverbatim; the UI no longer relabels them (no “Healthy”, “Not run”, “Stale (some keys)”) or rewrites a state from the last run: a failed last attempt is shown as its own fact (last attempt failed) beside the state,blockedis not folded intostale, and a task staysalways_runs. Health bars, group summaries, the graph legend, node colours, the sidebar dots and the state filters all come from one table keyed by the generatedCacheState, so a state the server adds cannot be left out. Failure mutes (this browser’slocalStorage), the demo “Preview failed check” and the placeholder asset graph shown before the server answered are gone: the UI shows exactly what the server reports, and a loading state until it does. - UI: the Playwright suites gate CI again (#807). Of the seven specs failing on main, six were stale after #753, #776 and #777 (
.barca-run-steps,executed/cachedcounts,21,950 / 28,404, “Retrying” status, “Preview failed check”, “Muted · 1”) and one was the node panel crashing on a node definition without afile(stub data only; the panel now leaves the source line out instead). The grouped specs run against a project declared in groups (ui/e2e-groups/fixture), served for real, instead of stubbing/groupsand/state; they also caught the grouped page writing a URL change (a search typed right after opening a group, or after going up a level) against the render’s copy of the URL, which reopened the group: changes are now applied to the URL as it is. - Stop metadata backups from holding up every other barca process: a
barca servewith a store hashed and copied the whole database under its lock, so a CLI command beside it waited for the copy (about 6 s per command against a 1.5 GB database, now 0.02 s). Only the log fold takes the lock; a read transaction keeps the file still while it is copied. scripts/check-fast.shin a tree without a.venv(or whosematurin developfailed) skips the Python tests with one line saying how to make the venv and exits 1, instead of running hundreds of tests against a missing binary.
0.39.5 (2026-11-04)
Bug Fixes
- UI: one state vocabulary everywhere. A task or sensor shows its last execution (Healthy, Failed, Not run) in tables, as group health already did; Not run, Unknown and Always runs are grey wherever they appear, leaving the queued colour to queued run work; “State unknown” is “Unknown”. Node, file and group names use the sans-serif instead of monospace, dark-theme borders and hover/selection backgrounds have more contrast, and table rows stack a name over its file at any width, with the table beside the node panel leaving out last success, typical and next run instead of squeezing every column.
- One
CacheStateenum (crates/barca-core/src/cache_state.rs) is the only spelling of a node’s cache state:barca status --json(cache.state,summary), the--statefilter, the server’s node state and the UI’s generated types all use its eight values (cached,unsynced,stale,never_run,partial,blocked,unknown,always_runs); a state from a newer server decodes asunknowninstead of failing the client (#802).specs/behavior/cache-decisions.mdrecords it. - A
--read-onlyserver reading beside a writer no longer loses reads todatabase disk image is malformed(a cache lookup counted as a miss, a failed request). Its check of the database file’s header closed a descriptor of the file, which drops every SQLite lock the process holds on it, so a writer in another process closing its last connection took the database as its alone: it checkpointed past the reader’s snapshot and deleted the write-ahead log under the reader’s queries. barca now reads the database file only through a descriptor it keeps open, as SQLite does. The same applied to abarca serveprocess’s own reads during its metadata backups.
Performance
- A run that executes a step writes its cost estimates in the ledger’s transaction instead of a second one: one commit (a sync of the metadata log) fewer, about 0.7 ms of the one-asset pipeline’s 38 ms on the benchmark machine (
benchmarks/RESULTS.md, 2026-11-04).
Documentation
- Measured 0.39.4 on the trivial pipeline: 31.7 ms from process start to exit (
benchmarks/trivial/bench.sh: 42-43 ms, with its shell wrapper), against 26.3 ms for 0.1.5 and 60.3 ms for 0.28.0 on the same machine. The README and the framework comparison now give this number instead of 0.28’s;benchmarks/RESULTS.mdattributes the time per phase, and the manual gives the measured cost of sorting a streamed partition (about twice the unsorted write). - CI’s merge tier runs the performance budgets (
scripts/perf-gate.py: the trivial pipeline’s wall time, coordinator CPU and memory, and theincremental_dagcoordinator budgets), so a regression fails the merge queue (specs/behavior/performance.md, “Gates”). - The deprecated HTTP aliases (
POST /run,/run/{target},/get/{target},DELETE /run/{run_id},GET /status/{run_id},GET /events/{run_id}) andbarca.Clienthave one stated lifetime everywhere, the manual, the CLI contract, the OpenAPI spec andClient’sDeprecationWarning: no scheduled removal; a removal migratesClientfirst and lands as a breaking change in a minor release. - CLI contract:
partitions.failedandbatch_executionare marked new in 0.38.0 instead of “the next release”; a stale note promising a change to therun failed:line (shipped in 0.24.0) is gone;steps_page.nodes[].statusandblocked_by(fromhistory RUN_IDwith a server) are listed as experimental, andfailing_since,consecutive_failures,steps_failedandfirst_failureas HTTP-only. BARCA_TRANSFER_RETRIESis documented, and the configuration page now listsBARCA_LOG,BARCA_SLACK_WEBHOOK_URL,BARCA_SLACK_NOTIFY,BARCA_UI_URL,BARCA_TRACE_LIBRARIESandBARCA_SERVER_TOKEN. A test keeps everyBARCA_*variable in the source documented in the CLI contract or named as internal.- The landing page, Getting Started, Philosophy and Architecture no longer say barca never imports your source: it reads source statically, and a nonliteral
partitions(...)orbatches(...)expression and abatches_byfunction are evaluated in a resolver subprocess that imports the module. - The cache reason
not_planned(stateunknown), whichstatuscould already report, is listed in the OpenAPICache.reasonenum, the CLI contract andbarca docs status; the contract’s lists also gain theblockedstate and theupstream_failedreason. Tests keep the code’s states and reasons equal to the OpenAPI enums. - The OpenAPI spec documents a skipped step’s reasons, including
upstream_key_failed, andspecs/README.mdstates each owner’s status for the current code (token auth and event replay shipped in 0.36.0). - DIRECTION.md carries the 0.39 cleanup’s order (#800), the releases 0.36.0 to 0.39.4, and the November decisions: the skipped cleanup weeks, shared in-flight steps kept on as experimental with the non-goal amended, the UI as a view of the ledger in the CLI’s state words, and store inspection settled by 0.36.0.
- Sharing in-flight asset steps between a server’s runs (0.39.4) is labelled experimental in
barca docs scheduling,barca docs server-mode, theserveentry ofbarca docs contractand the specs, with its three known gaps (#654). barca docs contractlists which experimental commands graduate in 0.40.0 (sql,history RUN_ID,doctor,state reset) and which stay experimental and why, and movesget -o json|prettyandrun -o/--outputfrom the experimental items to a new “Deprecated compat flags” section: they keep working, and none is removed before at least one minor release after a notice naming the replacement.barca docs partitions(“When a consumer’s keys are stale”) andbarca docs cachesay what a refresh does not reach: a refresh recomputes its own target’s cone, so after a refresh with another target that wrote new bytes, a consumer outside that cone stays cached on its old result andbarca statusreports itcached.--batch(batchover HTTP) groups keys and recomputes nothing on its own; name the consumer in--refresh. A test pins the refresh cascade topartitions_fromconsumers, batched and unbatched, on the CLI and underbarca servewith an artifact store (#799, which is not reproduced).
0.39.4 (2026-11-03)
Features
- Compute an asset step once when two runs of a
barca serveneed it at the same time: the second run waits for the first and reports the stepcached. Tasks, sensors and differing run hashes stay separate (#654).
Bug Fixes
- Record the steps a server run requeued by a deploy re-executes on the new code under their new run hashes, so the resumed run no longer serves and keeps the earlier attempt’s results (#794).
0.39.3 (2026-11-02)
Bug Fixes
- Automatically split failed partition batches into smaller calls, including after worker crashes, down to single partitions.
0.39.2 (2026-11-02)
Features
- Add
barca.sql()to the Python API for querying cached results with SQL.
Performance
- Scope UI duration estimates to each node’s partition history, avoiding scans of unrelated materializations.
0.39.1 (2026-10-31)
Features
- Refresh a key or set with
--refresh 'source[account=A],source[account=C]'while retaining the complete target DAG, cached siblings, batching and full fan-in publication (#784).
Bug Fixes
- A metadata database past its share of
[cache] max_sizeno longer evicts artifacts that fit. Upgrading a 40 GB database could delete every current result during the trim, costing a recompute of each. barca serveno longer panics now and then as it exits after a drain. The exit code was already 0.- A cache lookup the database cannot answer is a miss with a warning instead of a panic. A
--read-onlyserver beside a writer runningVACUUMwas seen to readdatabase disk image is malformed; the database itself was intact.
Documentation
contributing/testing.mddescribestests/simulation/sim.py, a seeded simulation of long server use with faults.
0.39.0 (2026-10-31)
Features
- A failed partition key blocks only the keys that read it. A
partitions_fromconsumer (or a node on the same dimensions) runs its other keys and skips its own key of the failure as a step with reasonupstream_key_failednaming the failed key; acollect()fan-in, an unpartitioned node or a node on other dimensions is still skipped whole (upstream_failed).barca statusandGET /statereport such a consumerblocked(detail39 of 39 missing keys wait on 'demand_forecast'),--state blockedselects them,summary.blockedcounts them, and the UI labels themBlocked · N keys wait on upstream. (#764) - The run page lists every planned node with what became of it: ran (keys, failed keys,
batched calls, compute time labelled as summed over the calls), cached, or skipped with the
failed node that blocked it, and states the target’s outcome at the top (
publish_plan did not run: upstream demand_forecast failed 7 keys). Successful keys sit behind their count, failed keys open at once. The runs table’s Steps column counts keys in one unit (3,077 ran · 3 cached) and a batched node’s failure readsdemand_forecast: 7 keys failed · ….GET /runs/{id}gainssteps_page.nodes[].statusandblocked_by, andGET /runssteps_failed(experimental). (#758) - The node panel of a partitioned node is actionable: the key bar always shows its failed
segment and the legend says
7 failedin red; typical time is per run in the table (~2.2s / run) and per batched call in the panel (0.4s / call · 5 calls), never0.0s / key; last attempt and history come before the key list, which starts closed past 10 failed keys; error lines are in the failure colour, wrap, and have a copy button; a key search that matches no failed key widens to every key and says so; each key row offers Run this key and shows its artifact path; the source path is project-relative with Copy path, and the editor link appears only for a root listed in localStoragebarca.editor-roots. (#763) - The command palette (⌘K) finds a partition key: a query that looks like one (
ra-02541,account=ra-02541) asks every partitioned node and listsdemand_forecast · account=ra-02541 · failed 2m agorows that open the node panel with that key searched; with an empty query, nodes and groups come before runs. (#759) - The UI shows every absolute time in one zone, local or UTC, chosen with a toggle next to the theme switch and remembered like the theme. Every absolute time names its zone, relative times keep the absolute time in their hover title, and the runs histogram, log timestamps, next-run cells and schedule times all follow the setting. (#761)
- The graph is readable at fit-to-screen: a fit never scales cards below 1:1 (13px names, 12px state labels); a bigger graph is centred on the selected node, else on its failed nodes. A consumer that did not run says on its card which failure upstream blocked it. Arrow keys move the selection, Enter opens the panel, Escape closes it. (#767)
- Starting a run from any page (a node’s Run button, the Failures view’s Retry, the topbar)
shows one line with the run id link, its progress, and its outcome (
succeeded in 2.3s,7 keys failed), refreshing the rows it touched. A group’s Contents reads3 assets · 1 task; a node’s Duration is its last run’s time summed over its keys and batched calls, with the breakdown on hover.GET /staterows gain an optionallast_run. (#766) - The UI’s tables are compact: 44px rows whose headers never wrap, and beside the node panel a
table scrolls sideways instead of growing. A failed row’s error is 13px in the failed colour,
sub-labels are 12px, identifiers (node, file, key, run id, target, error) are in the mono
font everywhere, and a name that does not fit is cut at its start but stays one piece of
text, so selecting a row copies
demand_forecast, notdeman\nd_forecast. The grouped view’s header fits a 1280×720 window on one line, and the connection dot is 12px with its text on hover or focus. (#765)
Bug Fixes
- The Failures view heads a partitioned node whose keys failed with their most common key error
(
BatchKeyFailed: … for <key>: …,7 of 3,077 keysunder it,+N more errorswhen they differ) instead of “failed, with no error recorded”; its cause headings show a real message instead of#-masked text; “Copy error” copies the key’s error and “Open run” opens the run that recorded it. (#757) - A page no longer stays on “barca serve is not reachable” after the server restarts: every query asks again every 5 s while its last fetch failed and refetches as soon as a health poll succeeds. While the server does not answer, a banner on every page says so, the connection badge is an amber pill, and every page in error has a Retry. Schedules no longer shows counts next to a “can’t load” error and keeps the last loaded rows under a notice when a refresh fails. (#760)
- A
group(...)call that is not assigned to a variable is registered (asgroup:<file>:<name>) instead of being silently dropped frombarca list --groups,GET /groupsand the Assets page. (#762) - The Tasks page’s default view also shows tasks that ran in the last 24 hours, its “Last run” counts include them, and zero-count state chips are hidden. (#766)
0.38.0 (2026-10-31)
Features
- A batched run says how many function calls it made. Each batched node gets one line before the
end-of-run line, also kept in
barca logs:[barca] batch:p.py:orders 7 calls, 3077 keys | import 0.1s, load 1.2s, compute 8.4s, split 3.1s, write 14.2s, then[barca] metadata 2.1s recording this run's results.get/runJSON gainssteps[].batch_executionandmetadata_seconds(experimental). The per-keystep:lines are unchanged. - The UI works with partitions at scale. A node with failed keys reads
40 of 3,077 keys failedinstead of stale, and its panel shows cached, failed and stale keys, the errors grouped, and a searchable list of keys. A run lists its nodes with keys, failures and calls, failed first, in place of a flat list of keys.GET /assets/{name}/partitionsis new;barca status --jsonandGET /stategainpartitions.failedandfailed_keys, andbarca history RUN_ID --jsongainssteps_page.nodes(experimental).
Bug Fixes
barca stats, and the UI’s history of a node, reported no runs for a partitioned node. It now counts runs, with time summed over the run’s keys andkeysandfailed_keyson each entry.
0.37.1 (2026-10-30)
Bug Fixes
- The metadata database no longer outgrows the size limit and pushes artifacts out. A production
database had reached 41 GB against a 13 GB limit whose artifacts took 7 GB, 36 GB of it the same
change digests repeated on every partition key’s row. A definition’s digests are now stored once
(
definition_components), and each database keeps to its own share of[cache] max_size, a tenth up to 1 GiB: past it, barca clears digests of old results and stored outcomes of old runs, thenVACUUMs, and only if that is not enough deletes old results whose file is gone and all but the last 1000 runs, with their logs. On a copy of that database this took 1m44s and left 848 MB with every result and run kept. Digests recorded before this release are cleared the first time this runs, so those nodes say a plainchangeduntil they next run (barca docs cache, “The metadata database”).
0.37.0 (2026-10-30)
Features
- The UI has a command palette (
⌘K) for any node, group, file or run, plus Run and Open graph. The node panel says what changed (Failed after a code change,Same code, new input), links the definition (billing.py:142, opens in VS Code), copies the artifact path and shows the first rows. Runs filters and the graph direction live in the URL (?status=,?q=,?hour=,?dir=). The Run button counts assets and sensors, which is what a get runs. barca list --jsonandGET /assetsgainfileandline;cache.change_causesinbarca status --jsonandGET /statesplits a stale or failed node’s change intocode_changed,inputs_changed,env_changedandupstream_stale, andcache.changedis now also set on a failed node that once succeeded.GET /assets/{name}/schematakes?sample=N(at most 20).- The UI’s graph answers a question: All pipelines is a map of files (one weighted edge per pair
of dependent files, drawn for the selected card when there are too many to read), a pipeline
of one group opens that group, unconnected members lie in a grid, inputs from outside a group
are faded ports, cards drop the
ASSETlabel, and the legend clears the zoom controls. - The UI spends its space on the table: title, breadcrumb and health share one row so a table starts within 120px of the top; run rows are one line; the queue appears only when something runs, waits or is held back; the server version moves to the tooltip of a connection dot in the top bar; List/Graph sits in the view it applies to. The sidebar collapses and lists each file’s groups; long node names are cut in the middle. The node panel leads with the error, with one compact stat row. Tasks, Failures, Runs and the node panel show errors the same way (headline, traceback on expand), and faint text now meets 4.5:1 contrast. The grouped page’s “Needs attention” filter is gone: Failures covers it.
- The UI’s Failures view groups failures by cause (first line, numbers normalised) with their
count and impact, biggest first, and each row can retry, copy the error, open its run, or be
muted in this browser until the node recovers.
Waiting on itshows0for a leaf and?while the graph loads. Grouped tables open worst first with a?sort=control, show Failures, Age and Duration instead of Output, and name rows by the distinct part of their id. Tasks open on what needs attention; Show all (?state=all) lists the rest. - The UI uses one name and one meaning per state. Green means healthy only: links, selection and
the primary button are neutral; red colours only the failed count, a column of states is dot and
text (pills stay for failed and running). States read Healthy, Stale (
Stale (some keys)), Failed, Running, Not run in every badge, legend, card and tooltip, and a check ischeckeverywhere (a task namedcheck__*orvalidate__*).getis gone from the buttons: Run names its target and size (Run invoices_00,Run billing.py (506 nodes)), works with nothing selected, andRun all 8,070 nodesasks first; the count is the assets and sensors agetruns. GET /runsrows havefirst_failure(node_id,error), andGET /staterows havelast_success_at,failing_sinceandconsecutive_failures. The UI shows them: asset, group and failure tables say how late each row is (Last success, failing since, runs failed in a row); a failed run with no run-level error names its first failed step and that error; Steps reads21,950 / 28,404 · stopped at <node>. Every time is relative with absolute UTC on hover, in one format. The Runs activity strip has an hour axis, a now marker, a tooltip per bar naming what failed first, and clicking a bar filters the list to that hour.
Bug Fixes
- The UI’s minimap draws its nodes (it was empty), appears only from 60 nodes and fits the graph beside it; names just over 10 characters also cut in the middle in narrow table columns.
- UI: Reset database shows only for a database barca cannot use, not on every page. Sidebar health
dots use whole-project state and show no dot until a file’s state is all known, instead of
judging a file by the part in view. All pipelines → Graph fits every domain on screen with nothing selected.
#/?pipeline=…&show=failureskeeps its filters through the redirect to Assets.
0.36.1 (2026-10-30)
Features
-
The UI answers “what is broken, and why” on projects of thousands of nodes. Every view shows its scope’s health as a bar (
77 failed · 2,111 stale · 7,912 healthy), group rows show the same breakdown, and a Failures view lists every failure in scope with its error and how many nodes wait on it, most impact first. A node’s panel leads with its error, traceback and run, or with the failed upstream nodes a stale node waits on, and counts what depends on it. Search reaches every node in scope, rows are one line, and a graph above 1,500 nodes draws the selected node’s lineage instead of never finishing its layout; graphs open at a readable zoom, on the selected node, rather than shrunk to fit. The Runs page shows the last 24 hours hour by hour with filters for runs that did not succeed, and each failed run’s error. -
Experimental
GET /statetakes group ids intargets(group:FILE:NAME, every node in the group) andfiles=(every node of a source file). The UI scopes a group or pipeline that way: it listed every node id in the URL, which a server refused (431) for a pipeline or group of a few hundred nodes, leaving its states unavailable.
0.36.0 (2026-10-30)
Breaking
-
Server event IDs use an attempt epoch and one-based sequence. Replay is bounded to 65,536 events or 16 MiB per run, 64 MiB across windows; expired replay returns 410, another attempt returns 409, and malformed/old numeric cursors return 400. CLI and browser clients resume acknowledged events; expired replay warns and follows the canonical outcome.
logs -f --serverexits 3 on an unfillable transcript gap. Older servers keep replay-count fallback. -
Served runs’ end-of-run metadata backups now share the routine backup interval. Completion still records the run locally, but no longer promises an immediate remote metadata copy. Standalone final backups and the server’s graceful-shutdown backup remain enabled.
-
Status inspection can reuse cloud availability and remote shape observations for five minutes. Local file changes invalidate evidence immediately; required reads and ledger publication still verify directly. This bounds repeated inspection work without changing asset freshness rules.
Performance
- Reuse bounded, file-identity-keyed digest and shape evidence across status requests and metadata refreshes; prefer verified local shapes. Keep at most 8 MiB/8192 entries per environment, limit individual values to 64 KiB, and bound cold inspection readers to eight. Refreshes, confirmed upload repairs and credential/import changes invalidate affected evidence.
Features
-
Resume CLI and browser run streams using attempt-scoped
Last-Event-IDcursors. Replay retains at most 65,536 events/16 MiB per run and 64 MiB across runs. When replay has expired, execution clients show a gap notice and follow the accepted run’s outcome without resubmitting work;logs -freports incomplete output as an infrastructure error. -
Connect the UI with a bootstrap code or API token, manage named tokens, and show new secrets once with explicit expiry choices. Tab-scoped credentials cover ordinary requests and fetch-based event streams; disconnect/revocation clears the connection and UI cache.
-
Opt into server-issued project bearer tokens with
[server] auth = "token",BARCA_SERVER_AUTH, orserve --auth. Localtokens bootstrapcreates a one-use recovery grant; HTTP token creation/list/revocation works in read-only mode, stores digests outside metadata backups, and closes revoked or expired event streams. -
Send server bearer credentials from
BARCA_SERVER_TOKEN, or Basic credentials from URL userinfo, consistently across execution, ledger, streaming and cancellation requests in the CLI and deprecated Python client. Reject mixed credentials and redirects outside the configured server origin/path, redact reflected credentials in HTTP errors, and keep the reserved bearer variable out of Python helper environments. -
Report local metadata backups outside the cache budget while retaining the five-copy rotation. Doctor and GC distinguish budgeted, backup and physical bytes; status adds an experimental project-wide
disk_usagesummary using maintained cache accounting without walking artifacts. Physical totals continue to include backups. -
Configure routine metadata backup cadence with
[remote] backup_intervalorBARCA_BACKUP_INTERVAL(default"1m", or"off"). A shared per-database gate applies before copying, hashing and uploading, survives process restarts, and retains dirty recorder progress when a request is skipped.
Bug Fixes
-
Avoid retaining inspection evidence for files changed within the last second, preventing rapid delete/recreate identity collisions from preserving stale local values.
-
Detect release merge groups from their checked-out commit so they run full emulator, DuckDB and integration gates even when the CI event context omits commit-message data.
-
Restore a metadata file onto a fresh host by creating its destination metadata directory. Restoring ledger backups leaves project authentication state separate and unchanged.
-
Validate token creation expiry while holding the auth-state lock, using the same private clock as bootstrap and validation; deterministic clock tests cover expiry boundaries and rotation.
Documentation
-
Record RFC-0016’s accepted design for opt-in server tokens and attempt-scoped event-stream resume, including bootstrap, browser credential handling, revocation and bounded replay. The implementation adds bounded replay with CLI and browser recovery.
-
CI runs in three tiers: a pull request runs the static checks, a merge group runs those plus the Rust tests, the wheel and the quick Python subset in
scripts/fast-tests.txt(about two minutes), and a release PR and its merge group run everything, with the object-store emulators, the duckdb 1.x rerun and the minute checkpoint test on.scripts/check-fast.shbuilds the venv’s barca with thefastprofile instead of--release, and runs the same quick subset. The release workflow builds the UI inside each wheel job from a cache keyed onui/instead of waiting on a separate job, waits for the published wheel on PyPI once instead of in each verification job, and skips the barca.sh deploy with a warning when the Cloudflare secrets are missing instead of failing the run.
0.35.3 (2026-10-29)
Bug Fixes
- A batched step’s DuckDB, Arrow or polars table is split into keys sorted by every column, so
a refresh that returns the same rows in another order keeps its
cutoff=Trueconsumers cached; before, a parallel producer’s row order changed the artifact bytes and reran them. The first refresh after upgrading rewrites each key’s artifact and reruns its consumers once. Values that compare equal but differ in representation (-0.0and0.0, distinct NaNs, strings under a case-insensitive collation) still need normalizing in the step.
Documentation
- Record the accepted configurable metadata backup cadence and separate local-backup accounting design in RFC-0015 for #706. Runtime behavior is unchanged.
0.35.2 (2026-10-29)
Features
-
Make CLI help concise, group root commands by purpose, and add
--exampleson commands and nested commands for the complete tested example collection. Detailed behavior stays in the built-in manual; help and examples run without loading a project. -
Experimental
GET /state?targets=a,bcomputes only those nodes and their upstream dependencies, including duration queries; omitted or empty targets keep the whole graph. This lets the UI request status for the open pipeline (#708, #710).
Bug Fixes
-
The release helper checks its changed-file allowlist in a fixed locale, so a valid version bump also passes on hosts whose filename collation differs from byte order.
-
Server URL userinfo is omitted from CLI errors and announcements, ledger warnings, stream drop messages, SQL provenance and doctor output (including JSON and older recorded errors). Requests retain their URL credentials, and pending posts keep matching the same server (#706, credential masking).
-
The grouped assets page now runs the selected node from the topbar in both list and graph views, and every node panel has the same action: cache-aware
getfor assets and sensors,runfor tasks. Read-only servers disable both controls. Accepted runs show as running before the first stream event; their details are available through View run (#709). -
The assets page and sidebar render groups, graph layout and pipeline counts from metadata before status arrives. Cache state shows as checking and fills in without moving rows or graph nodes; a status error leaves the graph visible. Opening a pipeline or group requests only its upstream status cone, while All pipelines requests the whole graph (#710).
Performance
barca serve --read-onlyreads current WAL metadata in place, warms status at startup even with an external writer, and moves fallback copies, migrations and duration reads off the request threads. Latest sensor observations use indexed seeks per key; eviction checks group the eviction index before checking for a later restore. On the synthetic #708 fixture (benchmarks/planning_pipeline/bench_status.py: 27 files, 373 nodes, seven groups, 500,000 observations, 1.15 GB DB),/statetakes 0.42 s with a writer committing every 0.2 s; concurrent/health,/assetsand/groupspeak at 0.009 s (19 samples per route). This measures inspection of synthetic history, not the production deployment (#708).
Documentation
-
Simplify first-use documentation around cached assets, tasks, partitions and remote execution. Start with the base install; make SQL and shared-store setup optional, and distinguish server execution from local computation against shared server state.
-
Bring DIRECTION.md through 0.35.1 and record the decided order after it: the 0.35.2 server/UI fixes, 0.36.0 backup/credential/resume RFCs, then feedback cleanup. Keep unresolved partition costs open and distinguish approved direction from shipped behavior.
-
Record reproducible overlap, bootstrap and inspection measurements for #654–656, including a synthetic 1,000-node/1.2-million-key workload. These gaps remain open; the benchmark records distinguish coordinator memory, worker costs and responsive health checks from expensive status recomputation.
0.35.1 (2026-10-28)
Bug Fixes
barca serveno longer stops starting runs while it measures.barca/against its size limit. A full walk (at start-up without.barca/gc-state.json, at least once a day, when over the limit) read every metadata row in one query under barca’s lock and looked at the file of every row on one of the server’s two event-loop threads: on a project with 465,000 artifact files and 2.8M results, a run asked for at start-up was accepted after 209 s and took 232 s. The walk now reads 20,000 rows at a time under the lock, runs on a thread of its own, takes file sizes from the walk instead of looking at each row’s file again, and a run that ends while it walks skips its own walk: the same run was accepted at once and took 33 s. A full walk of a project with its artifact files in place (465,000 files, 2.8M results) takes 148 to 159 s instead of 280 to 290 s, and plans the same evictions.- Runs with a remote artifact store no longer fail when planning takes longer than 10 s: the transfer helper’s hello is answered as soon as it connects, instead of after planning finishes (#702).
0.35.0 (2026-10-28)
Bug Fixes
barca serveloads apartitions_fromconsumer in another file than its source when the source’s keys come from an expression (partitions(KEYS)). The server evaluated the expression again for each consumer, in the consumer’s module, and refused the node withNameError: name 'KEYS' is not defined; the CLI loaded it. Each expression is now evaluated once per module and load, so the server also starts in 0.3 s where a project of 1,000 partitioned nodes took 19 s (960 interpreters started, now 10).
Performance
- Deciding the cache state of many partition keys is faster again:
barca statusover 1,000 nodes with 1.2M keys takes 7.5 s instead of 12.2 s, and so doesGET /stateand the decisions every run makes. Since 0.34.0 a one-key cache lookup compiled its SQL again for every key (the move fromtursoto libSQL lost the statement cache); a reader now compiles it once, and the keys of a partitioned step are looked up a few thousand to a query. GET /runsandbarca historyread each listed run’s first failed step from a new partial index,idx_mat_failed, instead of every row of the run: 115k rows for a run of a 115k-key node, read again on each poll of the web UI’s runs list. Opening an older metadata DB builds the index once, about ten seconds for 3M rows.- The web UI stays responsive with a thousand nodes. The assets and groups tables render the rows in view only (26 instead of 1,000 on a 1,000-node project; with the CPU slowed four times, a poll during a run no longer blocks the page, where it held it for 1.8 s), and keyboard navigation and sorting work as before. A graph of 300 nodes or more is laid out off the main thread, and the minimap is left out above 400 nodes, where it was most of the cost of a pan.
barca serve’s read routes no longer stall a run, or wait for one. They read the metadata DB in place, beside the run writing it (SQLite’s WAL mode), instead of taking the lock the run needs and copying the whole database first (gigabytes for a long history, written in full on Linux). A--read-onlyserver still reads copies.GET /stateafter a change waits at most a second for the new cache states and answers the last ones meanwhile (what is running is always current), and a failure to compute them is answered. On 1,000 partitioned nodes with 2.8M result rows (benchmarks/wide_partitions), the slowest read during a 115k-step server run polled as the web UI polls took 2.4 s instead of 53 s, and the run 58.5 s instead of 88.8 s (on a busy machine; 23 to 27 s on a quiet one).
0.34.0 (2026-10-27)
Breaking
- A decorator value barca cannot read from the source is an error when the file is read (exit
2, naming the argument, the file and line, and the form to write) instead of being read as
“not written” (#665): the path of
@sink(a path that was not a string literal declared no sink, so nothing was written),name=,description=,inputs=(not a dict literal, a key that is not a string literal, a value that names no step),partitions=(not a dict literal, a key that is not a string literal, a value that is notpartitions(...)/partitions_from(...)),serializer=(also on@sink; not a string literal, or an unknown format),freshness=(notAlways,ManualorSchedule(...)),tags=(not a dict of string literals),timeout_seconds=,retries=andretry_backoff=(not a number literal; these used to fall back to 300, 1 and 0.0). Replacement: write the value as a literal in the decorator (barca docs assets, “Values barca reads”);Nonestill reads as not written. Apartitions([...])list with an element that is not a string or integer literal is now evaluated by the resolver like any other key expression; that element used to be dropped.
Features
barca[sql]andbarca[test]accept duckdb 2 (duckdb>=1.4,<3, #567); CI runs the DuckDB tests on 1.x and 2.x. The floor rises from 1.1 to 1.4: duckdb 1.1 to 1.3 already did not work (dataset sinks passto_parquetarguments 1.1 rejects), and on 1.4 a remote CSV input read as a DuckDB relation failed withConnection has already been closed; it is kept open now. Barca no longer calls relation methods duckdb 2 removed or deprecated (barca sql --limitfailed withfetchone()), and discards a result a step left unread on the shared connection, which duckdb 2 otherwise lets block writing the step’s relation and the next step on that worker. Pipelines may need changes for duckdb 2 (rel.fetchone(), unreadexecute()results,->lambdas), and a database file duckdb 2 writes cannot be opened by 1.x:barca docs duckdb.
Bug Fixes
-
Preserve current partition results when a cache hit reuses an older materialization. Bound historical selection evidence per logical node and fall back to full validation on overflow.
-
A
collect()fan-in annotatedlist[duckdb.DuckDBPyRelation]no longer fails with duckdb 2 (“connection is busy with another call”): the worker made the relations on its one shared connection from several threads at once. It now makes them one at a time (#663). -
A failure in barca’s own code around a step (reading its inputs, splitting a batched call’s result, writing its result or its sinks) keeps its full traceback instead of reporting
"traceback": null, and the error says it failed in barca. Step errors carry a newphase(load_inputs,user_code,split_output,write_output,sink;nullwhen unknown) in the error envelope,barca.BarcaError.phase, and aserror_phaseinbarca history RUN_IDandGET /runs/{run_id}steps (#664). -
A sink is republished when its asset is served from cache under another run hash (#662). Barca records the run hash each
@sinklast published (per partition key for partitioned and dataset sinks, in a newsink_publicationstable of metadata format 1); a cache hit whose run hash differs writes the sink from the cached artifact without running the step, and one that matches writes nothing. Code A, then B, then A left the sink holding B.
Refactoring
-
Make freshness-proof replacement an explicit guarded transaction and cover interference, cache-only deletion and rollback; preserve the existing caller-held database locks.
-
Give durable result history one internal owner across progress, terminal, legacy-cache and server-ledger writes, preserving their transaction, receipt and deduplication rules.
0.33.1 (2026-10-27)
Refactoring
- Separate collected run results, attempt/timing evidence and ledger/report projections from execution decisions, preserving persistence, upload confirmation and cancellation ordering.
Documentation
- Consolidate freshness, execution, inspection and performance contracts; separate approved design from implemented behavior and unscheduled ideas. Remove superseded plans and check specification navigation, invariant ownership and finite concurrency models in CI. Record approved first-use, terminal feedback, project resource and agent interaction bounds without prescribing implementation; include a synthetic navigation scenario. Capture freshness requests, retries, snapshots, drain/recovery and configurable artifact retention, with remaining requirements questions saved for resuming the discussion. Map current architecture ownership and stage refactors with explicit implementation acceptance gates. Separate approved behavioral specs, interface contracts, unapproved proposals and engineering notes; standardize behavioral sections, remove completed plans and enforce the structure. Record a pre-merge audit with separate unresolved decisions, implementation disagreements and specification defects, plus controlled baseline reproduction probes. Correct audit blockers in the declaration model, upload/digest/log contracts and multiline link checking; separate invocation retry intent from the unresolved physical retry policy.
0.33.0 (2026-10-25)
Breaking
- Sensors now honor explicit change signals:
Trueadvances freshness even without data,Falseretains the previous observation, and(changed, value)also passes data. For content comparison, return the version value alone instead of(True, value). Worker protocol 5 requires matching native and Python packages.
Performance
- Default DAG runs reuse validated freshness per node before expanding partition keys. A changed key schedules only its affected chain; fresh keys keep their cache and history counts without coordinator objects for every key. Target selection also plans only its dependency cone. Workers compare source snapshots and report compact observations; scheduling priors and routine cache accounting avoid scanning every partition. The native coordinator uses the bundled, local-only libSQL driver and one CLI event loop. Existing SQLite-format history remains readable. Sensors still discover their keys, and changed fan-ins read all inputs. Explicit partition selections stream only requested source values into Rust, including cold runs and dry-run predictions.
0.32.0 (2026-10-24)
Breaking
-
Worker and transfer helpers now negotiate protocol 4. Protocol 3 helpers cannot execute a whole batch in one call and are refused before work starts, with an error asking to reinstall matching barca packages. The standalone stderr protocol stays at version 2.
-
barca runandbarca.run()on a partitioned task now return every key’s value in a dict keyed by partition key, with tables as JSON rows, on the server too. Previously they returned only the first key’s value. This also applies to a single--partitionselection: read its value from the keyed dict. More than 1000 keys use the same bounded summary asget; select keys explicitly to read them all. Unpartitioned task output is unchanged (#643).
Features
- Batched partitions (experimental, RFC-0013, #643):
batch=N,batch="all",batches([...])andbatches_by(fn, max_size=N)on partitioned assets and tasks group stale keys into fewer function calls. Each key keeps its own run hash, artifact, cutoff and sinks. A batch function receives lists of keys and keyed inputs, and returns a keyed dict or a table split by its partition columns;barca.Failed("reason")fails one key alone.--batchongetandrun,barca.get(batch=), run requests and schedules override grouping. History groups the keys of each call, and dry runs describe the grouping.
Bug Fixes
-
Await kill/wait jobs for rejected and disconnected worker starts before shutdown returns, preventing a fast CLI failure from leaving its helper alive.
-
Concurrent dataset sink writers no longer fail when another writer removes the empty shared staging directory while a new key starts writing.
-
Reading a large metadata database no longer prints internal
WHOPPER_FIND_FRAME_PROBEdiagnostics on stderr. Update the Turso dependency to 0.7.0-pre.19 (#645).
Documentation
- Retain deprecated HTTP route aliases for the public Python
Client; remove the expired promise to delete them after one minor release. New integrations should use/runs(#606).
0.31.0 (2026-10-23)
Breaking
barca serveno longer stops a run after 600 seconds. That limit was fixed and undocumented, and it cancelled long partitioned rebuilds; runs now have no time limit by default.barca serve --run-timeout 600(or[server] run_timeout_seconds = 600) restores it (#628).- A run of
barca servethat times out is recorded with statuserrorand the outcomerun timed out after Ns (<setting>); up to 0.30 it was recorded ascancelled. Automation that readcancelledas a timeout can match the outcome instead; a run cancelled withDELETE /runs/{id}is stillcancelled(#628). - A
partitions(<expression>)that raises is a load error:barca list,status,get,plananddoctorexit 2 naming the node with the traceback, andbarca servereports it inload_errorsand serves the rest of the project. Up to 0.30 it printed a warning and the node had no partition keys. Fix the expression, or make it return[]when there are no keys (#628).
Features
-
Production feedback from a pipeline under
barca serve(#627, #628). Why a run failed is one field away:barca history --jsonruns gain the flatfailed_nodeanderror(besidefailure), so--fields run_id,failed_node,errorworks, andbarca history RUN_IDshows the last 20 lines a failed step printed (steps[].output_tail, without the traceback it already shows). Per-step memory: the worker resets the kernel’s peak counter when a step starts, somax_rss_bytesis the step’s own peak, not the worker’s peak over every step it ran (Linux; elsewhere it is recorded only when a step raised the worker’s peak), measured up to the end of writing the result, so a returned DuckDB relation counts. It is inbarca history RUN_ID(PEAK_RSS,steps[].max_rss_bytesandcpu_seconds), inbarca stats(max_rss_bytesandmedian_max_rss_bytes, and eachrecent_runsentry’smax_rss_bytesandcpu_seconds) and inbarca.materializations. Bytes DuckDB spilled are not recorded (DuckDB keeps no total).barca statsrecent_runsentries gainrun_id. A project setting makes--envrequired:require_env = trueinbarca.tomlorBARCA_REQUIRE_ENV=1, and a command that touches an environment without--envorBARCA_ENVexits 2 naming the environments there are; without it, a command that names none in a project with several environments prints one note on stderr saying which it uses.@asset(deterministic=False)silences the “not deterministic” warning for an asset expected to return new bytes (caching and the run hash are unchanged); sensors never had it.barca planaccepts--jsonand--pretty, which change nothing (the plan is always JSON). OpenAPI specification 12:GET /runs/{run_id}steps gaincpu_seconds,max_rss_bytesandoutput_tail,GET /stats/{name}the memory keys andrun_id, andGET /historyrunsfailed_nodeanderror. -
The worker pool follows the capacity (#628): without
BARCA_POOL_SIZE, a run starts at most the cores or the capacity, whichever is smaller, so[execution] capacity = 1starts one worker, not one per core.[execution] pool_sizein barca.toml sets the pool (BARCA_POOL_SIZEwins over it).barca planaddspool_sourcebesidepool_size, andbarca doctor’scapacitycheck names the pool size and where it came from. -
A capacity shared by every run of
barca serve(experimental, #628):--capacity Nor[server] capacity = Nadmits theweight=of the steps of all runs against one budget, first come, first served across runs with the head reserved, so a light run proceeds beside a heavy rebuild while the heavy steps stay serialized, and a heavy step is never starved by light ones.GET /queue(barca queue --json) hascapacity: {total, source, in_use, runs, waiting},GET /healthhasqueue.capacity, and the web UI’s Runs page shows the weight in use and the waiting steps. -
The run timeout of
barca serveis configurable (#628):--run-timeout SECONDS,[server] run_timeout_seconds, and per scheduleSchedule(cron, timeout_seconds=N), which wins for its ticks; 0 is no limit. A run that times out is recorded aserrorwithrun timed out after Ns (<setting>). -
Under a supervisor (process 1 of a container, systemd, Kubernetes)
barca serveprints the stop grace period it needs at startup:[barca] stop grace: ... must allow at least Ns between SIGTERM and SIGKILL (drain timeout ...). With a drain timeout under 10 seconds the time it takes after the drain shrinks with it (half the drain timeout for stopped runs, at least 2 s; 1 s for connections), sodrain_timeout = 5needs 9 seconds and fits Docker’s default of 10 (#628). -
A run that was in flight when a supervisor killed the server during its drain (SIGKILL after SIGTERM) is put back in the queue by the next server instead of being recorded as interrupted, once per run. A server that dies without a stop signal (the OOM killer, a crash) still records its runs as interrupted, so a run that kills its server cannot loop (#628).
-
@asset(cutoff=True)(experimental): what reads the asset folds in the SHA-256 of the bytes it wrote instead of its run hash, so when it reruns and writes the same bytes, everything below it stays cached. A global step that reruns with unchanged output no longer reruns every partition key below it; per key on a partitioned asset; a cutoff dictpartitions_fromsource gives each key its own value. Its consumers are decided after it runs; until then--dry-runandbarca statusreport themunknownwith the new reasoncutoff_pending(also in theCachereason enum of OpenAPI specification 12). A--refreshcascade stops at a cutoff asset. Turningcutoffon or off reruns what reads the asset once (barca docs cache, “Early cutoff”) (#628).
Bug Fixes
partitions(<expression>)imports the asset’s module the way a worker does, with the project root onsys.path, so an expression that reads a project module from a file in a subdirectory works (#628). An expression that raises is a load error naming the node, with the traceback, inbarca list,barca status,get,GET /healthandbarca doctor; up to 0.30 the node silently got no partition keys.
Documentation
- The workflow pages 01, 02, 03 and 06 were re-run on 0.30.2 and restamped (#606): their
--agentsamples show the[barca] importingline, page 06’sstatustable agrees with its text, and page 03 now says a removed partition key leaves thebarca sqlview and that a failed key’s fix that changes the code runs every key again.
0.30.2 (2026-10-23)
Breaking
- A partitioned target of more than 1000 keys, returned without
--partition, no longer lists every key infinal_output: it is{"_barca_partitions": {"keys", "computed", "cached", "outputs", "truncated", "hint"}}, whereoutputsmaps only the keys the run computed (at most 1000) to their pointers, values or links, and-o pathprints those paths with a note on stderr. 1000 keys or fewer, and every--partitionselection, are unchanged. To read other keys, select them with--partition(partition=in Python;barca.get()raises for the summary) or query them withbarca sql(barca docs partitions, “Many keys”; #623).
Bug Fixes
barca serveno longer grows without bound under a schedule over many partition keys. At 200k keys each tick wrote about 82 MB of run outcome to the metadata DB and kept about 400 MB more memory; with one key changing per tick it records a 2 KB outcome (the DB grows about 50 KB a tick) and its memory stays flat. A run’s outcome lists the keys it computed and counts the cached ones; finished runs are kept in memory under a 64 MB budget as well as for an hour, oldest dropped first; the server returns the memory a run freed to the system when it ends;GET /runs/{run_id}andbarca history RUN_IDlist at most 1000 steps (?limit=N/--limit N,?all=true/--all) with a newsteps_page: {total, truncated}. Runs recorded before keep their outcomes and read as before (#623).
0.30.1 (2026-10-23)
Bug Fixes
- A metadata DB written before 0.29.2 opens again (#629): 0.29.2 to 0.30.0 refused it with exit 3
(“its
logstable has nostreamcolumn”) on every command,barca serveincluded, because the check that runs before the in-place migration did not know thelogs.streamandlogs.tscolumns that migration adds. Opening it now adds them in place and keeps every row; lines recorded before read as stdout with no time. Nobarca state resetis needed. A test now opens a database written by a release of every minor from 0.20 with the current build.
0.30.0 (2026-10-23)
Breaking
- A sink that cannot be written now fails its step, for every
@sink: the step’s error is aSinkErrornaming the sink, the run exits 1 with astep_failedenvelope, and the step is not recorded, so the next run tries it again. Up to 0.29 a failed sink printed[barca] SINK FAILED: ...on stderr and the asset succeeded; automation that grepped stderr for that line can rely on the exit code instead (#621).
Features
- Dataset sinks (#621): a
@sinkpath ending in/writes a Hive-partitioned dataset, one directory level per partition dimension of the asset (scored/retailer=r1/part-0.parquet), that DuckDB and pyarrow read as one table (read_parquet('scored/**/*.parquet', hive_partitioning = true)).partition_by=[...]adds levels from columns of the returned table,rows_per_file=caps the rows of each parquet file, andserializer="csv"or"json"(JSON Lines) write one file per partition. DuckDB writes a returned relation (streaming), polars a polars frame and pyarrow a pandas frame or Arrow table, all with the same layout. A cached key writes nothing; a key that runs is staged and swapped in for its own directory; a key the asset no longer has is deleted after the run. The sink owns its prefix (_barca_sink.json) and refuses one holding files barca did not write, and a write that makes many directories or small files prints a warning. Works on local paths and ons3://,gs://andabfs://.barca docs sinks, “Dataset sinks” and “How to choose partition columns”.
0.29.6 (2026-10-23)
Features
- Keyed partition sources:
partitions_from(source)wheresourceis an unpartitioned asset or sensor that returns a dict uses the dict’s keys as partition keys, passes each key its own value (as the parameter named after the source, or theinputs=key that names it), and folds only that value into the key’s run hash. One sensor query that returns{retailer: version}for every retailer then decides which keys exist and which changed: only a changed or new key runs, through a chain ofpartitions_fromassets, onbarca getand on abarca servetick.--dry-runandbarca statussay per key what changed (partitions.changed, experimental, with the newvalue IDentry), and the dry run’s table names it. With one key changed,barca getof a two-asset chain takes 0.32 s at 10k keys against 3.3 s with a sensor partitioned by key (which makes one call per key), and abarca servetick at 200k keys takes 4.3 to 4.6 s (benchmarks/keyed_partitions,benchmarks/RESULTS.md).barca docs partitions, “Updating only what changed, across many partitions”.
Performance
- A run over a partitioned node with many keys does less per key: the metadata DB keeps a
32 MiB page cache (one pass over 200k keys’ rows read the same pages from disk several times:
2.8 s against 0.25 s), a key read within the last hour is not stamped again (a 200k-key run
wrote 200k rows: 18 s), each returned key’s artifact is checked once instead of three times,
a key’s run hash is computed on several threads, and a partitioned step’s keys are not copied
for each worker chunk. With 0.29.4’s key lookups, a warm
barca getof a 200k-key chain with one key changed takes 7 s (31 s before both).
Bug Fixes
- An unpartitioned
@sensor()or asset returning a dict intopartitions_fromno longer runs its consumer once with no arguments (TypeError: keyed() missing 2 required positional arguments). A source that returns anything other than a list or a dict, a dict key that is not a string or an integer, or a value JSON cannot write fails the source step with an error naming the key or the expected types; an empty list or dict gives no keys, and acollectover them an empty list.
0.29.5 (2026-10-22)
Breaking
barca serveno longer refuses or cancels work when it stops. During a drain (SIGTERM or SIGINT)POST /runsand the older trigger routes answer202(200for the aliases) and queue the run for the next start, instead of503withRetry-After. At--drain-timeoutthe runs in flight are stopped and put back at the head of the queue, to start again from the beginning after the restart (exit 0), instead of being recordedcancelled(exit 1); a second signal still cancels them (exit 1). A requeued run is executed at least once: an interrupted step or task runs again. A--serverclient andbarca logs -f --serverwait up to 60 seconds (BARCA_SERVER_RECONNECT,0for the old behaviour) for a server whose stream broke, instead of exiting 3 at once.POST /runsanswers{"run_id", "status", "position"}(was{"run_id"});GET /healthgainsstarted_atandqueue.
Features
- A durable run queue for
barca serve: every run it accepts (POST /runs,--server, the UI, a scheduled tick) is recorded in the metadata DB before it answers, starts in order at most--max-runsat once ([server] max_runs, default one per core), and survives a restart: the next server prints[barca] resuming N queued runsand starts them under the same run ids.barca queue [pause|resume] --server(andGET /queue,POST /queue/pause,POST /queue/resume, a control on the UI’s Runs page) shows the queue and pauses it, a pause that is kept across restarts;--read-onlyrefuses it.barca docs scheduling, “Restarting without losing work”, is the operator recipe, with supervisor grace periods.
0.29.4 (2026-10-22)
Performance
- Inspection is fast at 300 assets with a 200k-key partitioned node and 2,000 runs
(
benchmarks/read_routes; numbers inbenchmarks/RESULTS.md): the web UI’s state view (GET /state) 76 s to 2 ms (2.2 s for the first request after a change),GET /nodes72 s to 1 ms,barca status76 s to 2.0 s,barca status --servertimed out (exit 3) to 13 ms,GET /history1.4 s to 42 ms, andbarca getwith every asset cached 14.1 s to 3.6 s. Queries that filtered node ids withsubstrorLIKEscanned the whole table once per node; they use the node id index now, with three partial indexes added within format 1 (idx_mat_changed,idx_mat_attempts,idx_mat_evicted; built on the first open after the upgrade, about 4 s for 400k rows). The dry run reads a node with many keys in one pass. The server keeps its parsed graph, one copy of the metadata DB and its status results until a source file or the database changes, answers an unchanged poll with304 Not Modified(ETagandIf-None-Matchon every inspection route), and computes/stateagain in the background while the UI is open.
0.29.3 (2026-10-22)
Breaking
--partitionnarrows the whole planned cone, not only the target. Every partitioned node with a selected dimension computes only the selected keys, upstream and downstream:barca get margin --partition region=apacno longer brings every key ofsalesup to date, and--refresh saleswith it recomputes onlysales[region=apac]. A selected key has the same run hash and artifact as in a full run, so a later full run serves it from cache. A fan-in thatcollects a narrowed node, and what is below it, is not run: the step reports itskippedwith reasonpartition_selection, stderr names it in one note, and the run still exits 0. The old target-only behaviour is gone, with no flag to keep it; run without--partitionfor every key. This breaking change ships in a patch release (0.29.3) by choice.
Features
-
Debugging a failed job from the CLI, here or from a server.
barca historytakes--status failed,...,--target NAME(the run’s target or job),--triggered-by manual|api|schedule|clientand--since 24h(or an RFC 3339 time or a date); they combine with AND, and--limit,totalandtruncatedcount the runs they keep. A failed run’s row ends with its first failed step and error (clean: ZeroDivisionError: division by zero), and JSON runs gainfailure: {node, error}.barca history RUN_IDshows one run: its fields, the schedule tick andclient_run_id, every step it recorded with attempts, time, run hash and artifact, each failed step’s error, traceback and how a dead worker ended (SIGKILL (possibly the OOM killer)), and a hint namingbarca logs RUN_ID --step STEP --stream stderr. Against a server the filters areGET /historyquery parameters and the detail readsGET /runs/{run_id}, whose steps gainpartition_key,attempts,run_hash, the artifact,error_type,error_message,error_tracebackandworker_exit, and which gainsjob,attempts,client_run_idandfailure. A run only this machine has saysbarca history RUN_ID --local. Cached steps are counted, not listed (barca docs status, “Finding and reading a failed run”). -
Debug a pipeline from the CLI, against a server too.
barca status --problemskeeps the nodes that need attention (every state butcachedandalways_runs, a task or sensor whose last run failed, a schedule that is paused or failing) and--state <states>the named cache states; the summary still counts every node and the JSON names the filter infilter(GET /nodes?state=&problems=over HTTP). The table’s WHY column shows the first line of a failed node’s error (failed: ZeroDivisionError: division by zero). A scheduled node hasscheduleinstatus --json(cron,next_fire,failures,max_failures,failing,paused,last_status,live) and a SCHEDULE column: from a server, its scheduler’s view, the numbersGET /scheduleand the web UI show; on this machine, what the metadata DB holds.barca doctorchecks a configured server (or--server <url>;--localskips it): its version and API version, its store against this project’s[remote], draining, files it failed to load, its scheduler and failing schedules, and the runs this machine has not posted to it, each failed check with what to do.barca docs agentshas a new “Debugging pipelines” section (barca docs status,barca docs doctor). -
barca sqlworks with server mode. With a server configured ([server] url,BARCA_SERVER) or--server <url>, the server says which result each view reads from its ledger (the newGET /sql/views: the current result per node, its store path, format and digest, and a partitioned asset’s current keys) and the query runs on this machine over the store, so a teammate queries results another laptop computed. View names, stale results and partition rules are a localbarca sql’s;--localqueries this machine’s own records; an unreachable server exits 3 naming--local, with no fallback; a result this machine has not posted yet (unsynced) is named, not mixed in. barca’s own records are queryable asbarca.runs(barca history --json),barca.materializations(one row per step result; with a server, the new paginatedGET /materializations) andbarca.nodes(barca status --json, flattened), locally and from a server (at most 10000 rows of each, with a note), andshow tableslists them. The server never runs SQL: DuckDB reads and writes files and the API has no authentication (barca docs sql, “With a server” and “barca’s own tables”). -
--partitionworks without a target (barca get --partition retailer=r1,r2: every asset and sensor, for those keys), onbarca run, onbarca plan, with--server(RunRequest.partition, now accepted forruntoo) and inbarca.get(..., partition=...), including withserver=. The JSON results ofget,run,--dry-runandplangainpartition_selection: the selection, each narrowed node’sselectedandskippedkey counts and theskipped_nodes. A value that is a key of no node with that dimension, or a dimension no node in the cone has, is a usage error. Selecting a few keys plans only those keys: at 200,000 keys on a three-asset chain, planning 10 keys takes 71 ms and 99 MB, against 378 ms and over 850 MB for every key (barca docs partitions, “Selecting keys”).
0.29.2 (2026-10-22)
Features
barca logsis a way to debug a live pipeline, here or on a server. Steps’ Python stderr is recorded with the run as well as their stdout:logging,warnings,print(..., file=sys.stderr)and the traceback of each failed attempt, still shown live as before. JSON lines gainstream(stdout|stderr) andts(when the line was written, RFC 3339 UTC with milliseconds);--stream stdout|stderrkeeps one stream and--timestampsputs the time before each text line. Lines are kept as the run goes, andbarca logs -ffollows a running run (without an id, the newest running one) and exits with its outcome: 0, 130 when cancelled, 1 otherwise. With a configured server (or--server),barca logsreads the server’s runs through the newGET /runs/{run_id}/logsand follows them over/runs/{run_id}/events;--localreads this machine’s. A run records at most 16 MiB of lines, then one[barca] log cap reachedline. The web UI shows stderr lines muted and each line’s time. Native writes to file descriptors 1 and 2 and subprocess output are still not recorded (barca docs logs, “Debugging a live pipeline”).
Bug Fixes
- In a terminal, a line printed while the progress bar is drawn (
checking artifact store,fetched N cached artifacts, a warning) is written above the bar instead of onto its line, which left a stray0/2bar frame on screen. - With a server configured (
[server] urlorBARCA_SERVER),barca getandbarca runno longer back up this machine’s metadata database, with or without--local: the server is the ledger and backs up its own. A client’s backups went into the server’s backup set (<store>/<env>/state/backups), rotated the server’s own copies out and could be restored in place of the server’s. barca statusshows the shape of a result held in a store that is a directory (file://), as every result is in server mode with such a store, instead of? (artifact file not found);--jsonshapeis the shape instead of{"note": "artifact file not found"}.
Documentation
-
A new guide, Share Results With a Team, sets up server mode in three steps: one committed
barca.toml,barca serve, andbarca getas usual. Every output sample and error message in it was captured from a real run of 0.29.1. -
Sample output on the site is re-captured on 0.29.1 (#503): the
barca status,barca historyandbarca listtables on the workflow pages, Pattern 01 and the cron comparison show times withUTC(local time forNEXT FIRE), and the execution-controls page shows the retry count (attempts=3), the timeout error naming the step, and the real elapsed time in the progress line. Thebarca docs statusexample of a changed-bytes line ends its time inUTC.DIRECTION.mdsays what shipped from 0.24.2 to 0.29.1 and what is next. -
The README opens with one headline, links to the docs, guide, changelog and contributing guide, a CI badge for
main, a docs badge and a pre-1.0 status note; a terminal image of a cold run, a cached run andbarca statusafter an edit; a “Why barca” list with the benchmark numbers frombenchmarks/RESULTS.md; and a screenshot of the web UI with runs in progress. The images are insite/public/readme/, linked by absolute URLs so they render on PyPI. CI now also runs on pushes tomain, so the badge has a result to show. -
The release workflow deploys the docs site, barca.sh, from each
v*tag once the GitHub Release and the PyPI upload are done, so the site matches the latest release instead of the last manualnpm run deploy. Nothing waits on the deploy, so a failure never blocks a release. It needs theCLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDrepository secrets and fails naming whichever is missing.
0.29.1 (2026-10-21)
Features
- Barca reports the environment variables a step reads without declaring them in
env=[...](#574). They are found statically, in the function and in the project helpers it reaches (os.environ[...],os.environ.get(...),os.getenv(...), pydantic settings fields), and reported as one[barca] warning:summary line per command, anundeclared_envitem per variable in thewarningsarray, andundeclared_envon eachget/run/--dry-runstep andstatusnode (experimental). Run hashes do not change: switching such a variable still serves the cached result, and the warning names theenv=fix.
Bug Fixes
-
With an artifact store, a
--refreshkilled after its upload and before its result was recorded no longer leaves the resultunsynced(mismatch) with a warning on everygetuntil another--refresh(#576). When a run fetches a store copy that is not the recorded one, the store’s copy wins as before, and the run now also records its digest: the warning is printed once, and the nextgetandbarca statusfind the resultcached. With a server, its ledger keeps its record as before. -
A variable declared with
env=[...]that is not set in barca’s environment is now read from the project’s.env(#575). A pipeline that loads.envat import (load_dotenv()) was hashed with the variable unset, so editing the value in.envserved the old result; now the edit re-runs the asset, andsteps[].envand the--agentline report the value from.env. The environment still wins over the file. Barca reads the file statically and does not set its values for the step.
Performance
-
A warm run with a store checks the store at most every 5 minutes (#593). A successful startup check is remembered in
.barca/gc-state.json, per environment, store URI and storage options, and agetorrunwithin 5 minutes of it starts no transfer helper unless it uploads or fetches something: no startup check and no check of its cached targets against the store. A run that does transfer starts the helper when it first needs it, and checks the store before its first fetch. A run after the window, another store or environment, pending uploads,--refresh,--refresh-allandget -o urlcheck at startup as before, and a failed transfer ends the window. So a store object deleted behind barca’s back is noticed within 5 minutes rather than by the next run (barca docs remote, “How often the store is checked”). On a 9-node project with two file sensors and a MinIO store on localhost (undertaskset), a warmbarca gettook 216 ms with the store and 54 ms without before this change, and 43 ms and 42 ms after it: the store adds about 1 ms instead of 160 ms, with no helper started. -
A lazy input read from the store (
duckdb.DuckDBPyRelation,pl.LazyFrame) fetches its byte ranges once per machine (#577). The ranges are kept in.barca/range-cache/<run_hash>-<version>/, keyed by the result’s run hash and the store object’s version, so a later run that reads the same ranges fetches nothing and a rewritten object is never served from stale bytes. The cache size limit counts the directories and evicts them with the leftovers, least recently used first.
Testing
- The remote planning-pipeline test reads the whole-tree and largest-process peak RSS from the same /proc snapshots, so under load the largest process can no longer read above the tree (#595).
0.29.0 (2026-10-21)
Breaking
-
Breaking:
inputs=keys and partition dimensions are checked against the function’s parameters when barca reads the file (#549). A key that is not a parameter, or a parameter with no default that is neither an input, a partition dimension nor apartitions_fromupstream, is a usage error (exit 2) naming the file, line, node and parameter, with “Did you mean”;list,plan,--dry-run,getandrunall report it before any step runs. Before, it was a workerTypeErrorafter the upstream steps ran, so a file holding such a step that was never run planned fine and now stops every command that reads it: fix the signature, or give the parameter a default.**kwargstakes any key; a@task’s parameters are not required (they are howparallel()branches get their arguments). -
Breaking: a retry after an exception may run in the same Python process as the failed attempt (#523): the worker that raised takes the retry, so module state (globals, caches, clients) carries over from the failed attempt instead of starting fresh. A step that needs a fresh interpreter per attempt should reset that state itself; a worker is still replaced after
sys.exit(),MemoryError, a timeout, a failed module import, an unfinishedparallel()exchange or a crash.
Features
-
Heavy steps can be kept from running all at once (experimental, #436). A new decorator argument
weight=N(a whole number, default 1) on@asset,@taskand@sensorsays how much of the pool’s capacity a step takes while it runs, and the steps running at once add up to at most the capacity: the pool size unless[execution] capacityin barca.toml orBARCA_CAPACITYsets it (the variable wins). Under a container’s memory limit, three heavy assets withweight=2and a capacity of 4 run two at a time instead of three, and light steps still use what is left; outputs and cache decisions do not change (weight=is not part of the run hash). A step heavier than the capacity runs alone, with a warning. A heavy step waiting for room is not overtaken by lighter steps that became ready after it. Partition keys andparallel()branches take their node’s weight.barca plangainspool_size,capacity,capacity_sourceandweights,--dry-rungainscapacityandsteps[].weight, andbarca doctoracapacitycheck. Seebarca docs assets, “Heavy steps”, andbarca docs scheduling, “Containers with a memory limit”. -
“What did my last run do?” is one command (#555).
barca historyhas a TARGET column between CMD and STATUS: the run’s job by function name (kpis,country_report,weekly_summary),allfor a run without targets, cut at 24 characters with…. History JSON gainsjob(additive):allor the resolved node ids, sorted and comma-separated,nullfor older runs;--fieldsaccepts it, andGET /historycarries it (OpenAPI specification 7).barca logswithout a run id reads the most recent run and names it on stderr (barca: logs of the most recent run: <run_id> (run notify, success, started ...)). -
barca statusand--dry-runsay what changed in a stale node’s run hash, not only that it changed (#558):cache.changed(status) andsteps[].changed(dry run) list the parts that differ from the node’s last successful materialization,code,decorator argument NAME,decorator NAME,helper FILE:NAME,input ID,sensor ID,env NAMEorkind, and the WHY column anddetailreadchanged: helper pipelines/common.py:bucket_ltv (+1 more). Each successful materialization records a short digest per part in a new nullablematerializations.componentscolumn (format 1, additive); a result recorded before keeps the plainchanged. -
Backups say which machine took them (#553). Each sidecar records
hostandproject(the project directory);barca state backupsshows a HOST column and gainshost,projectandminein JSON (nullfor a backup an older barca took, which is still listed and restored). Two machines backing up to one store, which is not supported without a server, now get one warning per command, on a backup orbarca state backups, when another machine took a backup after this one’s own, naming it and pointing at server mode. Pruning the store keeps the newest backup of every other machine taken in the last week (at most five), so one machine can no longer rotate out the other’s last backup, andbarca state restorewithout--fromrestores this machine’s newest backup, saying so when newer ones came from elsewhere (--from 1is the newest).barca state restore --jsongainshostandproject.
Bug Fixes
-
One byte formatter (#506): every size barca prints is in decimal units, as
[cache] max_sizeis written (KB= 1000 bytes). The upload, fetch and backup lines,barca state backupsandbarca sql’s “fetched” note used binary units labelledKB/MB(48.0 KBfor 49,152 bytes is now49.2 KB;barca sqlprinted40 bytes, now40 B).barca statusshape samples now encode values asbarca sqldoes: a NaN or infinite float isnull(it made the shape reader fail), a datetime is ISO 8601 withT, a decimal a number, bytes hex, a duration seconds. One helper runs barca’s JSON-in/JSON-out Python helpers, one runs a database transaction, and the Python file hash, identifier quoting and JSON conversion each have one copy; five unused functions are gone. -
A syntax error in a project helper module is reported when barca plans, not in the worker (#550). A command that plans a step of a file importing the module (directly, through other project modules, or inside a function:
get,run,--dry-run,plan,status) exits 2 before anything runs, withsyntax error in helpers.py: line 4, column 20: ..., the step, and the source line with a caret; commands whose steps do not import it, andbarca list, are unaffected. ASyntaxErrorthe worker still meets on an import barca cannot see (importlib.import_module) shows the file, line and caret instead of importlib’s frames. -
Naming one file of a package project works (#551):
barca run notify pipelines/reports.pyalso reads the pipeline files the named file takes inputs from (from pipelines.transforms import daily_revenue,asset_ref(...)), transitively, and keeps only the nodes the named file needs from them, sobarca get pipelines/reports.pydoes not runtransforms.py’s other assets. Node ids and cache entries match a whole-project run. An absolute import in a file inside a package resolves from the project root, and an “is imported from” error names the file the import reaches, never a path likepipelines/pipelines/transforms.py. An input only the whole project can resolve (a bare name, a re-export through__init__.py) says to name the defining file or drop the file arguments. -
barca state resetandbarca state restoreno longer leak the cache (#552). The artifacts the old database named, which no record names afterwards, are now tier-1 leftovers: the cache size limit evicts them first andbarca gc --max-size offdeletes them (an unnamed file is kept while a run is in progress, or for a minute after it is written unless it predates the database). Before, any file under.barca/artifacts/that no result named was counted and never deleted, so the limit could never be met. The reset still deletes nothing: it says how much stays and how to delete it, and the undo works until the files are evicted (an evicted one is computed again).barca gc --jsongainsheld(what,bytes,evictable: cached results, unreferenced files, metadata databases, the databases reset and restore moved aside, backups, other), and when it cannot reach its target it printsheld by:instead of only “nothing to evict”. The next check after a reset or restore measures.barca/again instead of trusting the last walk. -
A run held for its uploads and posted to the server later (#507) no longer prints “the function is not deterministic” for a hand-refreshed
Manualasset when the server answers that it held other bytes: the held post keeps which of its steps barca checks for changed bytes, so the later post warns for the same steps as one sent at the end of its run. A post kept by 0.28 or earlier still warns for every step it carries (#570).
Performance
-
A step that raises an exception no longer stops its worker (#523). The worker reports the failure with its traceback and takes its next step, so a failed partition key no longer costs a worker start (about 45 ms) and the rest of its batch is not sent again. With half of 10,000 keys failing (
benchmarks/partition_scaling/,FAIL_HALF=1, pool 8) a cold run takes 3.3 s instead of failing with “no workers available” after 96 s, and the coordinator sends 20,000 steps instead of re-sending batches (570,000 by the time it gave up). A retry after an exception may now run in the same process, so module state carries over from the failed attempt. A worker is still replaced aftersys.exit(),MemoryError, a timeout, a failed module import, an unfinishedparallel()exchange or a crash, and a crash still names the exit signal. -
A warm run with a store no longer pays for work that changes nothing (#554). A sensor that returned what the store already holds at its location, by this machine’s record of the confirmed upload, is not uploaded again. A run that recorded no new result takes no metadata backup at its end: nothing failed or was uploaded, every step it ran was such a sensor, and every earlier run is in a backup the store confirmed. Its run row goes with the next backup. The store is asked about all of a
get’s cached targets at once rather than one by one. On a 9-node project with two file sensors and a MinIO store on localhost, a warmbarca getwent from about 1.4 s to 0.5 s on a loaded machine (0.13 s without a store). What is left is the transfer helper’s start and the startup check, which agetof a cached target still needs.
Testing
- Three tests no longer fail by chance or by environment: the
barca state restorerefusal test waits for the server’s lock to be released instead of assuming it is immediate (a child process started by another test briefly holds it) (#524); the Datadog parallel-span test counts each span once and only its own run’s (ddtrace resends a payload it timed out on, and the fake Agent now serves requests concurrently) (#530); the coordination-socket tests build their fixtures under/tmp, so they pass when the runner’sTMPDIRis long (#571).
0.28.3 (2026-10-21)
Features
-
The web UI shows which pipelines and assets are running now, whoever started the run (the scheduler,
POST /runsfrom another client,barca get --server, or abarca get/barca runin a shell on the same.barca/): a running node pulses on the graph and the pipeline page, the assets list shows a Running badge with the elapsed time (keys done/total for a partitioned node) linking to the run, pipelines and groups count their running nodes, and the header shows “N runs in progress”.GET /stateandGET /assets/{name}gain arunningfield (run_id,triggered_by,started_at,step,partitions), andGET /runs?status=runninglists the runs in flight with theiractive_steps. The UI polls/stateevery 2 s while anything runs (#534). -
A mistyped name gets “Did you mean …?” (#556): a flag (
--refesh->--refresh), a subcommand (statsu->statsorstatus), a target (barca get amount->amounts), a--refreshname, abarca sqlview and abarca docstopic, by the rule decorator arguments already used: the closest names within one edit (two for a name longer than four characters), the best match only, or two that tie. The suggestion starts the JSON envelope’sremediationand has its own line in human mode;errorand the exit code (2) are unchanged, and barca never acts on it. clap’s misleadinguse '-- --refesh'tip is gone. This reverses the “no fuzzy suggestions” rule inbarca docs agents.
Bug Fixes
-
Usage errors point at
barca listonly when the target is the problem (#492): an unknown or ambiguous target (andbarca runwithout one) ends withRun `barca list <files>` ...; every other usage error (positionals in the wrong order,geton a task, an unknown--refreshname,-o urlwithout a cloud store, a removed setting such asBARCA_STATE, an invalidbarca.toml) carries its own remediation instead. Through--serveran ambiguous target’s envelope now has the same remediation as a local one. -
Quieter first run (#496): the worker’s
[barca] importing <module>line is printed only under--agent(and inbarca serve); the import time stays in the run JSON asimport_seconds. The human tables ofstatus,historyandstatsmark their timestampsUTC.barca docs --prettyis accepted (markdown, the default).barca statslabels its rate “Re-executed with unchanged inputs” and counts only the executions that repeated an earlier run hash; it was labelled “Cache hit rate” though cache hits are never recorded per asset. The JSON key is stillcache_hit_rate. -
A run whose upload failed is posted to the server’s ledger once a later command uploads it (#507). The run’s post is kept
unsynced(barca status:not_in_ledger) while its upload is pending, and the command whose retry uploads the results posts it before deciding its own steps, so that command and other machines get hits instead of computing it again. Before, such a run was never posted. A pending result dropped because its local file is gone is taken out of the post. -
A
Manualnode refreshed by hand now reaches what reads it (#548). Affects 0.28.0 and 0.28.1: afterbarca get fx --refresh fxgavefxa new result for the same code and inputs (a reference table that reads external data, the documented use ofManual), an asset that reads it kept serving its old cached result,barca statussaidcached, andbarca serveticks did the same; only a--refresh fxwith a target below it updated it. What reads aManualasset now hashes its bytes as well as its run hash, as a sensor’s consumers do, so it isstaleafter such a refresh and the nextbarca getor tick recomputes it; a refresh that gives the same bytes changes nothing below it. This holds for--partitionand for a key of a partitionedManualasset too. The run hash of every asset that reads aManualasset changes once: each recomputes once after upgrading. -
Refreshing a
Manualasset by hand no longer prints “produced different bytes for the same code and inputs; the function is not deterministic”, and neither the run’ssteps[].bytes_changednorbarca status’slast_bytes_changereports it: aManualasset is refreshed with the same code and inputs precisely to pick up new data (#548). -
A long
TMPDIR(over about 80 characters, as CI runners and sandboxes set) no longer fails every run withsocket bind: path must be shorter than SUN_LEN(exit 3). Barca’s coordination sockets (workers, the transfer helper) now live in a private per-user directory,$TMPDIR/barca-<uid>/(0700), falling back to/tmp/barca-<uid>/when that path would exceed the platform’s socket path limit (107 bytes on Linux, 103 on macOS); when neither fits, the error names the path, the limit and the fix. Sockets left by a killed coordinator are removed by the next run (#557). -
A sensor that returns a new value, or a task whose output changes, no longer prints “produced different bytes for the same code and inputs; the function is not deterministic”, and
barca statusno longer keeps that event for it. The byte check now applies to assets only. -
The end-of-run line
[barca] N/M steps | done in Xsshows the run’s wall time. It showed the sum of the steps’ times, so a run of parallel steps reported several times its real duration (done in 8.2sfor a 1.9 s run). -
A failed step’s message starts
Step '<node>' failed:instead ofWorker failed:, which read like a barca fault. Its remediation fits the failure: a timeout says to raisetimeout_seconds=, a worker that died without a Python exception (os._exit, a native crash, SIGKILL) says so, and “see the traceback” appears only when there is one. -
Refusals that are not barca failures no longer end with “Not a problem in your code: barca or its environment failed. Retrying may succeed.”: an unreachable or missing artifact store says what to check (URI, that the bucket exists, endpoint, credentials,
BARCA_REMOTE=off), andbarca state reset/restorerefused underbarca serveor a running run say what to do instead (the UI’s Reset database button orPOST /state/reset; stop the server; wait or cancel). -
A syntax error in a pipeline file names its line and column (
syntax error in pipeline.py: line 5, column 18: Expected ':', found newline) instead of a byte range (at byte range 112..113). -
barca getwith no target names at most five of the tasks it skipped (... and 37 more; barca list shows them) and suggestsbarca run <task>without repeating every discovered file. On the 116-node fixture the line was 2,000 characters.
Performance
- Small pipelines start faster (#560). Workers start together: when ready work has no idle
worker, every worker it can use (up to the pool size) is started at once and each joins when
it connects, where they started one at a time with a 30-40 ms wait for each; a one-step run
still starts one. A worker is ready for its first step in about 25 ms instead of 50 ms: it
imports
barca.api,barca.client,tracebackandconcurrent.futureson first use, and hookslogging(to collapse repeated warnings) only once something imports it. Steps waiting behind the ready ones count when the batch size judges a workload trivial, so a fan-out whose streams start with a few cheap steps uses the whole pool from the start. A warm run (every step cached) opens the metadata DB once to start, once per phase and once to record, where it opened it eleven times for a three-phase pipeline: the run’s start is one visit, the schema is read once per open,last_read_atis written in the ledger’s transaction, unchanged cost estimates are not written back, and a run that wrote nothing skips the cache size check when the last check under the same limit passed. Pinned and interleaved, median of 15, before -> after:trivial86 -> 47 ms,deep_diamond297 -> 90 ms,chain_100124 -> 97 ms, fan-out 500 x 50 ms 2.51 -> 1.82 s; warmdeep_diamond18 -> 13 ms. A worker’s protocol hello now carries itsworker_id(additive within protocol 3), andBARCA_TRACE_TIMINGprints the metadata DB opens.
Removed
- Committed junk and two broken examples (#497): the three
benchmarks/*/airflow/.venvsymlinks to macOS paths, the 0.1.5 macOS wheel underbenchmarks/partitioned_10k/wheels/andexamples/chain_100/stderr.txt. The Airflow harnesses take their venv fromBARCA_BENCH_AIRFLOW_VENV(benchmarks/README.md);examples/nested_tasksandexamples/pathological_assetsload again (theirbarca.tomldropped the unsupported[project]table), and a test runsbarca listin every example.
Documentation
-
CHANGELOG.mdis the source of release notes (#504). The release workflow publishes the version’s## <version> (<date>)section as the GitHub release body, from arelease-notesjob that the GitHub release and the PyPI upload both need, so a version without a section publishes nothing (scripts/changelog-section.py).cliff.tomland git-cliff are gone. Every section now uses## <version> (<date>)and the Breaking, Features, Bug Fixes, Performance, Removed and Documentation subsections, and the GitHub release bodies of 0.24.2 to 0.26.1 were rewritten from their sections. -
First-run pages show what barca prints today (#495): Getting Started, the Patterns pages and the CLI reference were re-captured on 0.27.0 (artifact paths with a small json preview, prefixed step output, no
importingline outside--agent), their “run with barca 0.18.0” stamps are gone,after=andwhen=are documented as the usage errors they now are, and the remote store is described everywhere as this machine’s backup and read-through cache, with sharing through a server. -
RFC statuses say what shipped (#502): the RFC template gains
Implemented (X.Y.Z)andPartially implemented (X.Y.Z); RFC-0007 is Implemented (0.27.0), with the route aliases’ removal left; RFC-0008 is Implemented (0.28.0); RFC-0009, 0010 and 0011 are Implemented (0.26.0) and RFC-0012 Implemented (0.25.0); RFC-0006 is Superseded in part.deploying.mdpins 0.28.0, and the guide, scheduling and core-constraints pages lose their 0.18.0 stamps (re-checked, including a multi-file example that needed a qualified import). -
barca docslists the manual in reading order (overview first, the contract last); the overview’s Topics list and Commands table are complete (logs,state,version), and every topic,cacheincluded, ends with its See also (#498). -
The README is the pitch, install, one example, the commands table and a “More” table that points at
barca docs <topic>and the site; reference detail lives in the manual (#499). -
The guide’s multi-file example imports
rowsasfrom pipelines.sources import rows; the barefrom sources import rowsit showed is refused (exit 2). The guide’s sensor section no longer ends with a dozen paragraphs of dependency-tracking release notes, and the scheduling tables say that sensors are polled by every run that needs them, whatever their freshness (Manual, their default, does not pin a sensor). -
Benchmarks re-run on barca 0.28.0, Dagster 1.13.26, Prefect 3.9.0 and Airflow 3.3.2 on one Linux machine;
benchmarks/RESULTS.mdand the comparison pages carry the new numbers in place of the June ones, plus barca’s trend across 0.1.5, 0.2.0, 0.24.2, 0.26.1 and 0.27.0 (#65).
0.28.2 (2026-10-21)
Bug Fixes
barca[sql]andbarca[test]requireduckdb>=1.1,<2. duckdb 2.0.0 (released 2026-10-21) removedDuckDBPyRelation.fetchone(), whichbarca sqluses to count rows, and refuses new work on a connection that has an unfinished result, which barca’s shared worker connection and many pipelines that return DuckDB relations rely on. A freshpip install 'barca[sql]'picked up 2.0.0 andbarca sqlfailed. Support for duckdb 2 is tracked separately.
0.28.1 (2026-10-21)
Bug Fixes
-
Concurrent
barca get/barca runprocesses in one project no longer fail now and then withFailed locking file '.barca/metadata.db'. File is locked by another process(exit 3) (#537). Since 0.28.0, setting up the metadata DB released barca’s cross-process lock before closing the database, so another process could open it while it was still held. -
An empty metadata.db is initialized, not refused (#537). A 0-byte
.barca/metadata.dbholds no history: atouch, a backup tool or a script that opened the path before barca created the database leaves one.barca serve,getandrunnow initialize it as a new database, with one line on stderr naming it ([barca] note: the metadata DB <path> was empty (0 bytes); initialized it as a new database), where a writerserveexited 3. A--read-onlyserver reads it as no history yet and leaves it alone. A file that is not SQLite, a newer format or a malformed schema is still refused, and an empty.barca/metadata.dbbeside a named env’s database still gets the stray-file warning.
0.28.0 (2026-10-21)
Breaking
-
Breaking: unscheduled
Alwaysnodes below a scheduled node, tasks included, now run at its ticks underbarca serve(RFC-0008, #253): a tick of a scheduled node is one run that brings it and everyAlwaysnode below it up to date. To keep a node out of its ticks, make itManualor give it its ownSchedule. -
Breaking:
barca get,barca run,POST /runs(so--servertoo) and ticks no longer recompute a staleManualnode, upstream or the target ofbarca get, unless--refreshnames it (RFC-0008, #253): they read its latest result and print[barca] note: <name> is Manual and stale; .... Name it in--refresh(or use--refresh-all) to recompute it. AManualnode that has never been computed is a usage error (exit 2) naming that command. AManualtask named as the target ofbarca runruns. The olderPOST /get/{target},POST /run/{target}andPOST /runaliases are unchanged. -
Breaking: a writer
barca servewhose metadata DB cannot be set up exits 3 before it binds, naming the file and what to do (upgrade barca,barca state restore, orbarca state reset), where it used to keep serving with the scheduler off and onescheduler disabledline (#513). A database barca cannot use (empty, not SQLite, a newer format, a malformed schema) is now one error,reason: "metadata_unusable"in the envelope (new optional key; CLI and HTTP), instead of a raw SQL error such asParse error: no such column;getandrunon a 0-bytemetadata.dbnow exit 3 instead of starting a new history in it. A--read-onlyserver keeps serving and reports the error.GET /healthgainsscheduler_enabledandmetadata_error.serve’s startup line is always printed and ends with; metadata <path> (db format <n>), and a stray empty or invalid.barca/metadata.dbbeside a named env’s database gets a warning naming both. A writer now waits for another process’s DB lock (up to 60 s) before it binds.
Features
-
barca servegivesAlwaysandManualtheir run-time meaning (RFC-0008, #253). A tick of a scheduled node is one run with several targets: an asset is computed when it has no result for its current code and inputs, a task fires when its last successful run used other inputs (or a task it reads ran since, or it never ran). The tick’s run keepstriggered_by: scheduleandscheduled_at, and itsbarca.runspan names every target. A failing scheduled node retries at every tick up to the newSchedule(cron, max_failures=N)(default 5), then is skipped and reportedfailing(failures,max_failures,failinginGET /schedule) until an explicit request or an input change; ticks skipped while a job is paused or still in flight do not count. Consecutive failures are kept in a newschedule_failurestable, added in place within metadata format 1. -
Reset the metadata database from the web UI and with
barca state reset(#508). A Reset database button on the “Can’t load pipeline” panel and in the sidebar, behind a dialog that says what happens and how to undo it, calls the newPOST /state/reset. The database and its-waland-shmmove aside tometadata.db.reset-<UTC>in the same directory and an empty one takes its place; nothing is deleted, artifacts stay, and a database that cannot be opened or migrated moves as it is. Refused with409(exit 3 on the CLI) while a run is pending or running,403under--read-only,503while draining.barca state resetasks in a terminal (--yesotherwise) and refuses whilebarca serveholds the environment. Undo withbarca state restore --from <the moved file>:--fromnow also takes a database file’s path. Experimental.
Bug Fixes
barca serveskips a cron tick while abarca getorbarca runstarted from a shell on the same project (the same.barca/) is running the same node, as it does for a run started over HTTP (#479): the skip names the CLI run’s id on stderr, inGET /schedule(skipped_for) and on the skippedbarca.runspan. Arunningrow whose process is gone (a killed run) does not block. A run now records its job (runs.job) when it starts, not only when it ends.
Performance
-
Recording a run in the metadata database prepares each per-row statement once instead of re-parsing its SQL for every row (#460): the step rows the recorder writes during the run, the terminal ledger’s success and failure rows, the read stamps (
last_read_at/evicted_at), pending uploads, captured logs and the cost estimates, which now commit in one transaction instead of one per partition key. A cold three-level partition chain at 20,000 keys goes from 12.0 s to 7.1 s, and the warm run from 3.3 s to 2.5 s. The rows written are unchanged. -
Skipping the dependents of failed partition keys no longer scans the ready queue once per skipped key (#461). When half of N keys failed while the rest waited, the coordinator touched the queue about N²/4 times (25 million at 10,000 keys); it now touches it about 3.5 N times. The ready queue keeps a membership set, so a skipped item is taken out in O(1) and its stale entry is dropped when it reaches the front. The skipped set is unchanged.
Documentation
-
The site’s reference pages that are manual topics (CLI Contract, Discovery, Doctor, Groups, Remote Storage, Server Mode, SQL, Telemetry) are generated from
crates/barca-cli/docs/*.mdwithbarca docs <topic>references turned into links, andcargo test -p barcafails when one differs from its topic (#501). This brings back in step the pages that had drifted (barca sqlreads CSV and evicts its.barca/sql-cache/copies;get --jsonalways returns a pointer), adds Server Mode and Groups to the sidebar, and lists the Reference pages alphabetically. -
barca docs cachereads concept, behaviour, reference: what a run hash covers, what is not followed, the cached/stale/evicted/unsynced states, forcing a recompute, the size limit. Its 0.18/0.19 upgrade notes moved to this file; its implementation guarantees tospecs/cache-decisions.md(#500).
0.27.0 (2026-10-20)
Breaking
- Breaking:
barca servedrains on SIGTERM or SIGINT instead of cancelling its runs at once (#190). New runs get503withRetry-After, the scheduler stops,GET /healthreports"status": "draining", and runs in flight finish, uploads included, for up to--drain-timeoutseconds (new flag;[server] drain_timeoutinbarca.toml; default 30). The server then exits 0. When the deadline passes or a second signal arrives first, the runs left are cancelled with reasonserver shutdown(in their logs, in/statuserror, and asbarca.reasonon thebarca.runspan) and the server exits 1, where it used to exit 0. For the old immediate cancel use--drain-timeout 0(it exits 1 when it cancels a run). Give the supervisor a stop grace period longer than the drain timeout (Docker’s default is 10 s). - Breaking (HTTP API): every error body is the CLI error envelope (
error,code,kind,remediation, …) instead of{"error"}alone (erroris still there).GET /assetsandGET /assets/{name}return thebarca list --jsonnode shape (freshnessa lowercase word, cron inschedule) and thebarca stats --jsonbody (idinstead ofnode_id).GET /runs/{id}returns the flat run view with itsoutcomeinstead of{run, steps, logs, result}. Run ids returned by the trigger routes are the database run ids.POST /run,POST /run/{target},POST /get/{target},DELETE /run/{run_id},GET /status/{run_id}andGET /events/{run_id}stay as aliases for one minor release; usePOST /runs,DELETE /runs/{run_id},GET /runs/{run_id}andGET /runs/{run_id}/events. Event streams now end afterrun_finishedand carry anid:per event. - Breaking: Datadog dashboards and monitors need updating. The
<DD_SERVICE>-pythonservice is gone:barca.executeand library spans are inDD_SERVICE, and libraries are no longer patched unless opted in (DD_PATCH_MODULES=<lib>:trueorBARCA_TRACE_LIBRARIES=1).barca.runresources use short names (run publish, wasrun pipeline.py:publish);barca.stepandbarca.executeresources are the node’s short name (was the node id, with the partition key, and the job forbarca.execute): filter by@barca.node_idor@barca.partitioninstead. The step tagbarca.nodeisbarca.node_id. Partition keys arebarca.partitionchild spans of onebarca.stepper node. Thebarca.serve.start,barca.serve.heartbeatandbarca.serve.stoptraces are replaced by thebarca.serve.upgauge (1, and 0 on stop) and its siblings: move monitors on those traces to the metric. Spantypeisworker(wascustom).
Features
barca serveruns the server half of the--serverrun contract (RFC-0007 §3.4, #393).POST /runstakes the flags ofbarca get/barca runas JSON and answers with the run’s database id at once (dry_runanswers with the--dry-runJSON); targets are checked first, in the CLI’s words.GET /runs/{run_id}/eventsstreams every stderr line a local run prints (line, taggedwhen: agent | always), step output (log), step results (step_finished, withcached: truefor cache hits) andrun_finishedwith the outcome, each event numbered (id:); a slow or reconnecting reader receives every event once, and the stream ends afterrun_finished.GET /runs/{run_id}answers with the outcome (the exact--jsonbody, or the failed-run body and error envelope) from the metadata DB, so it survives a restart;DELETE /runs/{run_id}cancels;GET /runs/{run_id}/outputserves the final artifact.GET /list,/nodes,/historyand/stats/{name}return the CLI’s--jsonbodies byte for byte,GET /projectdescribes the deployed tree, andGET /healthaddsapi_version,envandstore_uri. Runs recordtriggered_by(manual,api,schedule,client) and, for scheduled runs,scheduled_atandschedule_id, inbarca history --json,GET /runsand thebarca.runspan (barca.trigger,barca.scheduled_at,barca.schedule_id, #434). The web UI uses the new routes and shows what started each run.POST /schedule/{id}/pause(optionally?until=<RFC 3339>) andPOST /schedule/{id}/resumehold one schedule back without--no-schedule(#435).GET /schedulereportspaused,paused_untilandskip_reason; a paused job’s ticks are skipped with reasonpaused(also on the telemetry span) and are not caught up. Pauses are kept inschedule_state, so a restart does not resume a paused job.--server [<url>]runsget,run,status,list,historyandstatson abarca serveand prints the answer as the local command prints it: the same stdout JSON, the same stderr lines, the same exit codes, rendered by the same functions (#394, experimental). With no URL it usesBARCA_SERVER, then[server] urlinbarca.toml, and says so once on stderr; nothing configured is a usage error.--localignores a configured server (and is a usage error with--server);--serveronserve,plan,sql,doctor,logs,docsandversionis a usage error. A run streams its progress and step output, and Ctrl-C cancels it on the server (a second Ctrl-C exits 130 at once). A server that cannot be reached, is not barca or speaks another API version is exit 3 naming its URL; a stream that drops mid-run is exit 3 naming the run id. A named file that differs from the deployed one prints a note.get --serverprints the server’s artifact paths (paths by default);-o valueand--partitionwork as locally (RunRequest.values,RunRequest.partition), and-o urlis a usage error with--server.barca.get(..., server=True)andbarca.run(..., server=True)do the same from Python.barca.Clientis deprecated in favour of them and warns when constructed. The binary now carries an HTTPS client (reqwestwithrustls);POST /runswithfilesnow reads only those files, as the CLI does. Seebarca docs server-mode.- Server mode’s ledger (RFC-0007 §3.4 and §4.1, #402), experimental. With
[server] urlinbarca.toml(and[remote]pointing at the server’s store),barca getandbarca runstill run on this machine but ask the server’s ledger which run hashes exist (POST /ledger/lookup, one request for the plan), fetch the hits from the store, compute the misses here and, once their uploads are confirmed, post the run (POST /ledger/runs). The server checks every object in its store (a directory store by SHA-256, an object store by size) before it records the run astriggered_by: clientwith the laptop’s run id in the newclient_run_id(also inbarca history --json); a missing or mismatched object is409naming the node and records nothing. A refused or undelivered post leaves the run a success: a warning names it, it staysunsyncedin the newledger_poststable and the next command against the server sends it again. A run some of whose uploads are pending (#390) is not posted. A run hash the ledger holds with other bytes prints the non-determinism warning once. A server that cannot be reached is exit 3; a different or missing store is exit 2. The ledger is reached overhttp://orhttps://with the--serverclient, from[server] urlorBARCA_SERVER;--localruns against this machine’s ledger and touches nothing on the server (error remediations name it). With a server configured,barca status,barca historyandbarca statsanswer from the server ([barca] server <url> (<source>)once);barca statusaddslocalper node (this machine has a copy) and shows a result whose post is pending asunsyncedwithcache.reason: "not_in_ledger"(summary.unsyncedcounts them). New manual topic:barca docs server-mode. barca serve:BARCA_LOG=jsonwrites every line as one JSON object on stdout, withts, a reallevel(info,warning,error),msg, therun_idandnodeit is about, anddd.trace_id/dd.span_idwhen the Datadog integration is on, so a container’s logs join the run’s trace and are no longer all filed as errors. A step’s printed output becomesinfolines of its run. Experimental; without it nothing changes, andget/runkeep progress and errors on stderr (BARCA_LOGon another command prints a warning).barca.stepspans gainbarca.upstream(direct upstream ids) and, on a step that ran,barca.digest(#434).- Datadog traces show the pipeline (#482). Every span reports as one service,
DD_SERVICE(defaultbarca),type: worker,span.kind: internal, withenv,version,barca.versionandbarca.project.barca.runis named by the command and the targets’ short names (get daily_revenue) and, on a failure, names the first failed asset and its error (barca.failed_asset,error.type,error.message).barca.stepis one span per node, named by the node, withbarca.asset,barca.node_id,barca.file,barca.group(nestedgroup()path),barca.freshness,barca.schedule,barca.cachedand outcomeskippedfor a planned step that did not run. A partitioned node is one step withbarca.partitions.total/executed/ cached/failedand abarca.partitionchild per key that ran (up to 200 per node, 2,000 per run) and per failed key. Pythonbarca.executespans are named by the node too. Library spans are opt-in:DD_PATCH_MODULES,DD_TRACE_<LIB>_ENABLED, orBARCA_TRACE_LIBRARIES=1(experimental). Trace ids are 128-bit (_dd.p.tid); traces go to the Agent’s/v0.4/tracesas JSON and are kept with sampling priority 2.barca servereportsbarca.serve.up,barca.serve.schedules,barca.serve.filesandbarca.serve.nodesas DogStatsD gauges (DD_DOGSTATSD_URL,DD_DOGSTATSD_SOCKET, orDD_AGENT_HOST:DD_DOGSTATSD_PORT), with a Datadog event on start and stop.
0.26.1 (2026-10-20)
Bug Fixes
- Metadata backups no longer overwrite each other when several directories back up to one
store location in the same second (#487). A backup is now named by the UTC time to the
millisecond plus a short suffix from the host name, the database’s path and the copy’s digest
(
2026-10-14T18-02-11.482Z-3f9a1c2e.db).barca state backupsstays newest first andbarca state restore --from <name>takes both these names and the to-the-second ones 0.26.0 wrote, which are still listed and pruned.
Removed
- Leftovers of the shared history: barca-core’s
state_syncmodule (its deadline and helper-error code moved tohelper_proc; the WAL-fold wrapper only its own test called is deleted), and the cache manual’s limitation about eviction marks in a pushed history. Docs, specs and comments no longer describe a shared-history push. No user-visible surface changes.
0.26.0 (2026-10-20)
Breaking
-
Breaking: a remote store fails soft once the steps are done (#390). When every step succeeded and only an artifact upload (or a metadata backup) failed,
getandrunexit 0 (was 3) with one warning, adduploads: {pending, error, nodes}to the run JSON and--dry-run, and record the results;barca statusshows themunsynced/local_only(summary.unsynced) until the next command that opens the store uploads them first. Readuploadsinstead of exit 3 to detect unpublished results. -
Breaking: the shared history (
optimisticmode) is removed (RFC-0009, #403; closes #243):[remote] state,[remote] state_uri,[remote] push_retries,BARCA_STATE,BARCA_STATE_URI,BARCA_PUSH_RETRIES, the pull before each run, the conditional push after it and themetadata.db.prevcopy. Abarca.tomlor environment that still sets one is a usage error (exit 2) naming it and barca 0.26.0, even underBARCA_REMOTE=off: remove it. A single machine gets backups of its history with no setting (below); teams that shared history through a bucket move to a server (RFC-0007), and a wiped machine gets its history back withbarca state restore. The oldstate/metadata.dbobject is ignored.
Features
-
With a remote store (
[remote] uri), the metadata DB is backed up on the minute checkpoint and at the end of everygetandrun, and every minute it changed underbarca serve, to.barca/backups/and{uri}/{env}/state/backups/(five copies each, with a<UTC>.jsonsidecar). Newbarca state backupslists them andbarca state restore [--from N|NAME]puts one back after validating it, keeping the replaced database asmetadata.db.pre-restore. A backup that fails to upload is a warning anduploads.error, never a failed run (#403). -
barca statuswith a store reportsunsyncedwithcache.reasonstore_onlyandmismatchbesideslocal_only, by comparing this machine’s copy, the store object and the recorded digest;barca getrepairs anunsyncedtarget without running a step (upload, fetch, or re-upload with the changed-bytes warning andsteps[].bytes_changed) (#403). -
barca serveruns with a remote store (it used to requireBARCA_STATE=off) and backs its history up. -
Signed URLs (experimental, RFC-0011, #452):
barca.signed_url(uri, expires=3600)returns a time-limited, read-only HTTPS link to any object in S3 (also R2 and MinIO), GCS or Azure, signed with the credentials barca already uses: SigV4 on S3, V4 on GCS (IAMsignBlobwhen there is no key), and on Azure a service SAS with an account key or a user delegation SAS fromDefaultAzureCredential.barca get <target> -o url [--expires 30m|12h|7d|seconds]prints one link per result (default 1 hour, at most 7 days); with--jsoneach_barca_artifactgainsurlandurl_expires_at. Links download as<node>.<ext>. The URL goes to stdout only. -
Slack notifications (RFC-0010, #450): set
BARCA_SLACK_WEBHOOK_URLto an incoming webhook and barca posts when a job starts failing, when it recovers, and once a day while it keeps failing, forbarca get,barca runand every runbarca servestarts.BARCA_SLACK_NOTIFY(changes,failures,all) andBARCA_UI_URL(run links) tune it. A delivery failure is one warning that never names the webhook URL, and never changes a run’s outcome. Runs now record their canonical job (runs.job) and the last post per job is kept in a newnotificationstable, both added in place within metadata format 1. The binary now carries an HTTPS client (reqwestwithrustls), shared with the coming--serverclient. Seebarca docs telemetry. -
A cached result whose upload is pending is never evicted by the cache size limit, and
.barca/backups/counts toward it but is never evicted.barca get -o urluploads alocal onlyresult before signing it.
0.25.1 (2026-10-20)
Bug Fixes
-
barca statusreports a partitioned node’s last materialization by a fixed rule: the latest run (by row id), and within it the first key in sort order. Before, it was whichever key finished last, so two identical runs could report different keys (#475). -
The release workflow’s
verify-published-linuxjobs wait for the PyPI simple index to serve a new version before installing it, retrying every 20 s for up to 12 minutes (PyPI’s CDN caches the index withmax-age=600), so a release no longer needs a manual rerun for index lag (#480).
0.25.0 (2026-10-20)
Breaking
-
Breaking:
barca getprints artifact paths by default (#404). In--json(and whenever stdout is piped)final_outputis always the pointer{"_barca_artifact": {"path", "format", "size_bytes"}}, for json artifacts too, and a terminal shows the path with a small json value previewed under it. The old default, the value, is-o value(-o value --jsonfor the JSON line);-o pathprints only the paths.barca.get()still returns the value. -
Breaking: a partitioned target returns every key, sorted, never one key (#287):
final_outputis an object keyed by partition key ("region=emea"), andbarca.get()returns a dict of key to value.--partition region=emea,amer(or a JSON object for compound keys) selects keys, computes only those and scopes--refreshof the target;barca.get(..., partition=...)does the same. -
Breaking:
.barca/now has a size limit,[cache] max_sizeinbarca.tomlorBARCA_CACHE_MAX_SIZE("20GB","500MB","20GiB", bytes,"10%"of the filesystem, or"off"), defaulting to 10% of the filesystem.barca/is on. After everygetandrun, after everyserverun and once a minute underserve, a cache over its limit is evicted down to 80% of it: leftovers (dead processes’ staging,*.moved-aside*directories,sql-cache/copies), then superseded results, then local copies the artifact store holds, then the least recently read results; never the command’s own outputs, results a run in flight holds, a storelessManualnode’s current result, or the metadata databases. An evicted result is fetched or computed again under the same run hash when something needs it (step and status reasonevicted). A project whose cache was larger than the limit sees more fetches and recomputes after upgrading;max_size = "off"restores the old unbounded behaviour. New, experimental:barca gc [--dry-run] [--max-size SIZE] [--json] [--env ENV], thecachekey onget/runresults, thecache_sizecheck ofbarca doctor, andcacheinGET /health.materializationsgainsevicted_atandlast_read_at(additive, metadata format 1); rows are never deleted (RFC-0012, #457).
0.24.3 (2026-10-20)
Bug Fixes
- Open a metadata database last written by barca 0.21 to 0.23. Since 0.24.0, every command
refused one with exit 3 (“its
materializationstable has nobytes_changedcolumn”), andbarca statusfailed with “no such column: bytes_changed”. barca now adds the missing column in place, in one transaction, keeping every row; the older release still reads the result.
Performance
- Cold runs of large partitioned pipelines scale linearly with the number of keys again: a three-level chain of 20,000 keys runs cold in about 9.5 s instead of about 245 s, with a 0.55 GB coordinator instead of 5.3 GB (#345). Each key of a step used to wait on every key of the previous step in its stream through its own edge; one shared gate per step now keeps the same ordering. Dispatch also finds an upstream’s output by id instead of scanning every output, and the end-of-run check no longer scans every item on each event.
0.24.2 (2026-10-20)
Bug Fixes
-
barca serve: a cron tick is skipped while any run of the same node is pending or running, including one started byPOST /get,POST /run/{task}orPOST /run, not only one the scheduler started (#432). The skip is logged with the run in flight, reported aslast_skippedandskipped_forinGET /schedule, and sent to telemetry as abarca.runspan with statusskippedandbarca.reason: in_flight. -
Refresh dependency lockfiles (
uv.lock,ui/,site/, the dagster benchmark) to clear the open critical and high Dependabot alerts: PyJWT 2.15.1, aiohttp 3.14.5, cryptography 50.0.2, urllib3 2.8.0, oauthlib 4.0.0, astro 7.4.1, wrangler 4.151.3, react-router 7.18.4 and vitest 4.1.12, plus patched transitives. -
Failed
barca.steptelemetry spans now report their duration, from the first attempt to the permanent failure (retries included; a timeout reports about its timeout), instead of a zero-length span at the end of the run. -
A worker that dies while running a step (#433) now names how it ended instead of a bare
worker disconnected:worker for <node> exited with SIGKILL (possibly the OOM killer), another signal by name, orexited with code N, in the step error, the run JSON and the failure summary.get,runandserveprint[barca] env <env> (<source>); artifact store <store>once on stderr at startup whendefault_envfrombarca.tomlor an artifact store is in effect. -
Follow a project module reached through another module’s
import(from wrapper import helpersorwrapper.helpers.f()wherewrapper.pydoesimport helpers), and follow import chains at any depth instead of stopping six project modules deep; modules that import each other terminate. Editing such a helper now invalidates its consumers. Existing affected consumers may recompute once after upgrading.
0.24.0 (2026-10-15)
Breaking
-
Breaking: agent completion and permanent failure lines append
attempts=Nafter retries. Allow this optional suffix when parsing those lines, or read the structuredsteps[].attemptsfield instead. -
Breaking: removed
barca get|run --no-cacheandbarca.get(no_cache=...). Use--refresh-allandrefresh_all=True, respectively. The CLI alias is now an unknown-flag usage error (exit 2); Python rejects the removed keyword.
Features
-
Add
barca doctorprerequisite checks, credential identity diagnostics and a documented local-only debugging profile. -
Run JSON reports executed-step durations and attempts, with slow module imports reported separately. History JSON totals recorded materialization attempts; stats retains per-materialization attempts. Timeout errors identify the step id.
Bug Fixes
-
Follow project helper references in exception handler types, including exception tuples and
except*. Editing those helpers invalidates their consumers. Existing affected consumers may recompute once after upgrading. -
Follow project helper references inside set literals. Editing those helpers now invalidates their cached consumers. Existing affected consumers may recompute once after upgrading.
-
Follow project helper calls in assignment receivers and indices, including annotated, unpacked, loop, context-manager and comprehension targets. Editing such a helper now invalidates affected cached assets.
-
Follow project helper references in
for/whileelse:blocks so edits invalidate affected cached assets. -
Follow project helper values, classes and mapping keys in
matchpatterns so edits invalidate affected cached assets. -
Follow project helper references in ordinary function/class decorators, including nested definitions and decorator-factory arguments.
-
Retain project-helper provenance for unpacked and augmented module constants, including aliases captured before later overwrites. Consumers conservatively hash the module source and static references.
-
Track project star imports in ordinary helper modules conservatively, including functions/classes, captured constants, forwarded exports, multiple/conditional imports and transitive stars.
-
Follow project helper references in function and lambda default arguments, including nested functions and keyword-only defaults. Editing those helpers now invalidates their consumers. Existing affected consumers may recompute once after upgrading.
-
Retain project-helper provenance for names, functions and classes bound inside module-level
for,while,withandmatchblocks. Consumers conservatively hash module source and static references.
0.20.0 (2026-10-08)
Bug Fixes
- A run records the kernel it ran on (boot id), its pid namespace, its start time and a marker
in
.barca/run-owners/, andbarca historyreports itinterruptedonly on an observation that its process is gone (specs/cache-decisions.md); otherwise it staysrunning. A run started by 0.19.0 or earlier is still judged by its process id and host name, so in a container, on another machine or once its process id is reused it can stayrunning. 0.18.1 reported a run killed by a restart of a machine whose project is on a network filesystem asinterrupted, from the host name and process id; from 0.20.0 such a run staysrunning.
0.19.0 (2026-10-08)
Breaking
- Breaking: the definition part of the run hash covers the decorator arguments that count
(
barca docs cache, “Which decorator arguments count”) instead of the decorators’ text as written. Up to 0.18 any edit there (a new partition key, a description, a comment, a reformat) re-ran the step for every key, and everything downstream (#283). Every step’s hash is computed differently, so every step recomputes once on the first run after upgrading, in every project and every environment (--env); the run after that is served from cache. Results written by 0.18 stay in.barca/metadata.dband on disk under their old run hashes; 0.19 neither reads nor deletes them. With an artifact store, 0.19 writes every result under its new run hash and leaves 0.18 results in the store alone; the two versions do not reuse each other’s results. Run hashes in the JSON ofget,run(also--dry-run) andstatuschange value; no command, flag or JSON key changed.
0.18.0 (2026-10-07)
Bug Fixes
- The run hash follows classes, imports inside function bodies, aliased
fromimports, modules used as values, and root modules imported from a subdirectory (#194). A step recomputes once after upgrading, with its downstream steps, if its function or a helper it reaches uses: a class defined in the project; a project module imported inside a function or class body;from module import name as aliasof a project module; a project module as a value (getattr(helpers, name), passinghelpersalong); from a pipeline in a subdirectory, a module in the project root; a helper module named like a pipeline file in another directory (both are hashed now); or, for a pipeline file inside a package, project modules imported asfrom .helpers import forfrom pkg.helpers import f(these now resolve from the root, as they do when the step runs). A step whose helpers import the same name from two different modules outside the project (from numpy import arrayandfrom jax.numpy import array) had two possible hashes, picked at random on every run, and missed its cache about half the time; it now has one, and recomputes once if its last result was recorded under the other. Every other step keeps its hash and its cached results.
0.12.0 (2026-10-03)
Features
- A sensor’s output is part of the run hash of every asset that reads it (#188). Previously an
asset reading a sensor was served from cache whatever the sensor returned. Assets that read a
sensor re-run once after upgrading; pipelines without sensors keep their run hashes and
caches.
--dry-runandbarca statuspredict from the sensor’s last recorded output, and a sensor recorded before this version has none, so its consumers areunknownuntil it runs.
0.10.0 (2026-10-02)
Breaking
- Breaking:
--refreshcascades downstream by default: it re-runs the named assets and every asset downstream of them in the target’s cone (#168). Previously it re-ran only the named assets and left their downstream assets cached;--no-cascadekeeps that behaviour.
0.1.2 to 0.8.0 (summary)
Breaking
barca runis now cache-aware for upstream assets by default (same asbarca get); the task itself still always re-runs. Previously every upstream asset was force-rerun.--burstis renamed to--refresh <a,b>; add--refresh-all(alias--no-cache) to restore the old default. Python API:barca.run(..., burst=[...])is nowrefresh=[...]/refresh_all=True.
Features
-
--dry-runonbarca getandbarca run: reports, for the exact command and flags, which steps are served from cache and which will run and why (cached/run/partial/unknown), without executing or writing anything. Real runs now report the same per step in astepsarray (and[barca] step:<id> cachedin--agentmode). The dry run and the real run share one decision function, and tests check that the predictedwill_runequals the real run’ssteps_executed. -
barca docs: a manual compiled into the binary (concepts, output formats, caching, tasks, partitions, scheduling, runnable examples, conventions for scripts and AI agents). Every command’s--helpnow ends with runnable examples, andlist,historyandstatstake--json. Docs, help examples and JSON output are now part of the feature workflow (see CLAUDE.md); tests execute the manual’s examples. -
DuckDB: steps returning a
DuckDBPyRelationor a pyarrowTableare written as parquet withoutserializer="parquet"(a relation used to crash with “cannot pickle”, a Table was silently pickled). Barca now owns one DuckDB connection per worker process and binds every duckdb-typed input as a view named after its parameter for the step, so SQL by name works in helpers without bind code;barca.duckdb_connection()exposes the connection for one-time configuration (extensions, credentials, settings). Steps that mix relations from their ownduckdb.connect()with inputs still fail, but the failure now carries abarca:note explaining the conflict and the fix instead of only DuckDB’s cryptic message. -
Sub-minute cron scheduling:
Schedule(...)now accepts a 6-field cron with a leading seconds field (e.g.*/15 * * * * *— every 15 seconds); thebarca servescheduler evaluates at 1-second resolution. 5-field crons are unchanged (seconds pinned to0). -
Built-in cron scheduler in
barca serve: enforces@asset/@task/@sensorfreshness=Schedule(...), timezone-aware (--timezone), durable catch-up on restart, self-overlap skip, and live status viaGET /schedule; toggle with--no-schedule. -
Shared remote state and content-addressed artifacts:
barca.tomlconfig,--envenvironment separation, and remote artifact storage (Azure/S3/GCS/R2 via fsspec) with the metadata DB pushed/pulled as a blob. -
Minimal standalone scheduler example under
examples/scheduler. -
Async-native core: the async runtime is owned by the caller, with cancellable runs.
-
Centralized cron parsing behind a single
CronExpr::parsehelper so validation, the scheduler, and the/schedulehandler share one grammar.
Bug Fixes
-
--refreshis no longer easy to misuse: a name that is not an upstream asset is an error that lists the valid names (it used to silently do nothing),--refresh a bsays to use a comma instead of failing with “No such file”, and barca warns when a refresh leaves cached assets downstream of it stale (run hashes cover upstream hashes, not outputs, so they stay cached). -
A step that runs for 15 s or more is now reported on stderr (
[barca] still running (45s): ...,BARCA_PROGRESS_SECSto tune) in every mode, so a slow step no longer looks hung. -
Partitioned assets are now cached per key. Previously every partition re-executed on each run (a
TODOin the coordinator); now unchanged keys are served from cache and only new or changed keys run, with the fan-in re-running only when its inputs change. -
Concurrent barca processes in one project no longer fail with
Failed locking file '.barca/metadata.db'. File is locked by another process. Turso opens the DB single-process (its multi-process mode is experimental), andbarca get/runheld the DB open for the whole run. Barca now holds a short cross-process lock (.barca/metadata.db.lock) only while it reads or writes the DB and releases it while your Python runs, so processes queue instead of failing.
Documentation
-
Surface the task-scheduler workflow in the README and docs splash; new “Barca vs cron / systemd timers” comparison; sub-minute cron documented across the Scheduling guide and reference.
-
Real
freshness=(and other) keyword parameters on the@asset/@sensor/@taskPython stubs for IDE autocomplete and type checking.
0.1.1 (2026-06-04)
Features
- Correct main.py entry-point description in CLAUDE.md
- Clean up stale files from pre-Rust rewrite
- Polish: Result errors, default subcommand, versions, test isolation, README
- V0.1.1: Engine refactor + clap CLI + Python API
Bug Fixes
- Fix 3 PR review issues: artifact key collision, binary caching, deterministic partition get
0.1.0 (2026-06-04)
Features
- File-based artifact persistence: replace JSON-over-stderr with format-aware artifacts
- Require Python >=3.12, build wheels for 3.12/3.13/3.14
- Restore full release workflow from prior working config
- Use PYPI_API_TOKEN secret for PyPI publish (already configured)
- Engine hardening: refactor, protocol, first-class partitions, P0 fixes, CI/CD
- Rewrite gap tests: cross-file, sensor, partition (drop ops concerns)
- Add gap tests documenting known cache/staleness limitations
- Add cache fuzz tests: 100 random DAGs × mutate × verify staleness
- Add dependency cone analysis for staleness detection
- Implement
barca getwith cache-hit detection and staleness tracking - Add cache/staleness integration tests (TDD: all currently fail)
- Add dagster server-mode partition benchmarks
- Add dagster/prefect for partition benchmarks, run full comparison
- Add partition benchmarks with partition-aligned stream assignment
- Implement dynamic partition eval and partitions_from resolution
- Implement static partition expansion and dynamic partition parsing
- Clean up DagNode duplication, remove dead code, tighten types
- Comprehensive planner tests documenting DAG shape → execution plan mapping
- Make parser pure: return Result, add 10 edge case tests
- Add integration tests for CLI behavior
- Add Airflow benchmarks: trivial, chain_100, deep_diamond, fan_out_500_50ms
- Complete benchmark fairness: server-mode dagster, parallel prefect
- WIP: Add server-mode benchmark scaffolding for dagster
- Address benchmark fairness concerns (ExSidius/barca#35)
- Add ETL pipeline, wide join, and incremental backfill benchmarks
- Add large_payloads, map_reduce, and multi_file_discovery benchmarks
- Add deep_diamond, wide_layers, and mixed_io_cpu benchmarks
- Wire up multi-process dispatch: workers communicate via stdout, Rust owns DB
- Add execution planner: Dag → decompose → Topology → plan → ExecutionPlan
- Add spaceflights, fan_out_500, and fan_out_500_50ms benchmarks
- Add benchmark results README
- Use SmallVec for inputs/sinks/partition_keys (stack allocation for small collections)
- Add comprehensive grammar spec tests, fix int parsing
- Rewrite barca as Rust binary with Python execution runner
- Add AGENTS.md (#33)
- Replace Datastar/Jinja2 UI with React + shadcn/ui (#31)
- Add comprehensive tests for multicore asset execution (#30)
- Add learning path to README, show artifact path after refresh, fix broken examples (#29)
- Replace plain text CLI output with Rich-formatted tables and panels (#28)
- Consolidate three packages into one + GitHub install instructions (#25)
- Update documentation with GitHub installation and CLI options (#24)
- Switch from sqlite3 to libsql as primary DB driver for MVCC concurrency (#23)
- Update documentation: reflect notebook workflow, add MkDocs, improve code docs (#22)
- Add notebook workflow helpers: load_inputs, materialize, read_asset, list_versions (workflow 7) (#21)
- Make sensors first-class nodes with dedicated CLI, API, and display (workflow 6) (#20)
- Add spaceflights benchmark: 10-asset diamond DAG adapted from Kedro (#19)
- Add test coverage roadmap with detailed spec for 100+ new tests (#18)
- Improve dependency tracking with codebase merkle hash, snapshots, and batch worker (#17)
- Add benchmark suite: Barca vs Prefect vs Dagster orchestration performance (#16)
- Refactor to align with barca.allium: freshness, sinks, run/dev/prune (#32)
- Release polish: metadata, changelog, serializer= parsing, version
Bug Fixes
- Fix PyPI license metadata: use SPDX identifier instead of text table
- Fix all 11 PR review issues: CI, correctness, latent bugs, nits
- Fix all 3 staleness gaps: cross-file imports, sensor bypass, partition cascade
- Fix chain caching (ordered persist) + add cached benchmarks
- Fix run_hash consistency: 13/13 cache tests pass
- Fix: user print() statements no longer corrupt worker protocol
- Fix all clippy warnings, tighten idiomatic Rust
- Fix thread-safety in MetadataStore for concurrent per-thread usage (#27)
- Fix: make UI reactive to asset state changes after reset/reindex (#14)
- Fix: support bare @asset decorator (no parentheses) (#12)
Removed
- Drop linux-arm64 from release matrix (simsimd NEON cross-compile failure)
- Remove dead code: plan.rs, NodeState, classify_shape, stats
- Remove AssetStatusBadge web component; use data-persist for dark mode (#15)
Documentation
- Document Airflow 3 LocalExecutor limitations
- Document Airflow LocalExecutor limitation: requires PostgreSQL for parallelism
- Docs: fix datastar-reference for RC.8 syntax (#13)
- Docs: fix Quick Start so new users can actually run barca (#11)
0.0.3 (2026-03-14)
Features
- Chore: use cross for Linux CLI builds in just release
0.0.3rc1 (2026-03-14)
Features
- Ci: replace release workflow with local just release recipe
- Ci: use macos-latest for x86_64 macOS wheel (macos-13 unavailable)
- Chore: bump all crate versions to 0.0.3
- Ci: fix manylinux glibc compatibility for bundled CLI binary (#10)
- Init (#1)
- Initial commit
Bug Fixes
- Fix: use command -v to check for cargo-zigbuild
- Fix: use uv tool install ziglang + symlink to zig in setup recipe
- Fix: ignore untracked files in dirty check
- Fix: handle PEP 440 rc versions in just release (convert to semver for Cargo)