Skip to content

traj: recursive tail and cat return the whole tree, in order - #110

Merged
nickjalbert merged 1 commit into
laude-institute:mainfrom
MaxFreedomPollard:traj-recursive-tree
Sep 5, 2026
Merged

nickjalbert merged 1 commit into
laude-institute:mainfrom
MaxFreedomPollard:traj-recursive-tree

Conversation

@MaxFreedomPollard

Copy link
Copy Markdown
Contributor

What

traj tail -r and traj cat -r return nothing — on any trajectory whose steps
carry the stamps traj itself writes — and still exit 0.

$ traj cat --raw --filter type=thought | jq -r .content
parent-1
parent-2
$ traj cat -r --raw --filter type=thought | jq -r .content
$ traj cat -r --raw | wc -l ; echo "exit=$?"
0
exit=0

-r, --recursive Include steps from all sub-trajectories, interleaved is
offered on tail, cat, search and check. search -r and check -r walk
the tree fine; the two views that interleave are the ones that come back empty,
so the halves of the same flag disagree.

Why

_sorted_tree_steps is the only place in traj that sorts steps, and its key
comes from to_epoch. Three things were wrong with it, all silent.

1. The Z that gets added twice. capture() matches
<datetime><numeric offset> (colon optional); anything else falls through to
the catch-all, which keeps the whole string as .dt — and the next line
appends a "Z" to it:

(capture("^(?<dt>\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2})(?<sign>[+-])(?<oh>\\d{2}):?(?<om>\\d{2})$") //
 {dt: ., sign: "+", oh: "00", om: "00"}) |
...
((.dt + "Z") | fromdateiso8601) as $local_epoch |

Every stamp traj writes is UTC and already ends in Z (_iso_ts):

$ printf '%s\n' '{"ts":"2026-09-04T14:13:18.402Z"}' \
    | jq -r '(.ts|tostring|sub("\\.[0-9]+";"")) + "Z" | fromdateiso8601'
jq: error (at <stdin>:1): date "2026-09-04T14:13:18ZZ" does not match format "%Y-%m-%dT%H:%M:%SZ"

jq's stderr goes to /dev/null and its status is || true, so nothing
surfaces: sort gets an empty stream and the command exits 0. The only steps
that survive are ones still carrying the legacy numeric-offset spelling, which
capture() does match — so a tree containing one such step returns exactly
that one step and nothing else, which is what makes this confusing to hit. The
strip also takes the RFC-3339 lowercase z, which reached the parser malformed
before.

2. The key floored to the second. The fraction is stripped before parsing,
and a trajectory writes many steps a second, so most keys tie and sort(1)
falls back to its last-resort comparison of whole lines — the JSON text.
Fixing only the Z trades an empty result for a plausible but wrong one. On a
tree built with real traj append calls, with just the Z fixed:

true order:    zebra apple mango banana yak
cat -r:        zebra apple banana mango yak    <- mango and banana swapped
tail -r -n 2:  mango yak                       <- the two newest are banana, yak

GNU and BSD sort also disagree about which wrong answer you get. So the key
is now integer milliseconds — folded into the integer rather than left as a
decimal, so the numeric sort cannot depend on the locale decimal point.

3. An unparseable stamp deleted its step instead of sorting it somewhere.
Every other date read in the tree already guards this — bin/chat:487,554,
thinkers/_lib/common.sh:365, bin/thinkers:1033,
thinkers/responder/step:136,228 all use try fromdateiso8601 catch … or
fromdateiso8601?. bin/traj:782 was the one call site that did not, which
also left the function's own (.ts // .timestamp // "0") fallback dead — "0"
became "0Z" and errored.

Long-standing rather than a regression: (1) reproduces at 4ee873e~1 as well
as at main.

Why this is one change and not three

They are one defect — -r does not deliver what its help line promises — and
the parts are not separable in a useful way. Landing only (1) would replace a
visibly empty result with a plausible, silently mis-ordered one, which is
harder to notice and harder to debug; the red/green table below shows that
state failing 8 of 15 assertions. Landing (1) and (2) without (3) leaves the
same silent-drop class the PR exists to close, one line away in the same
function. Happy to split it if you would rather review them separately.

Not in this change

to_epoch still does not accept a bare epoch-seconds ts, which bin/traj's
display code does handle at lines 910 and 994. I left it alone because nothing
writes that shape — no code in bin/, thinkers/, tools/, web/, slack/
or telegram/ emits a numeric ts, and every stamp in tests/fixtures/ and
tests/golden/ is a quoted ISO string. Such a step is no longer dropped
either way: with the guard it sorts to the front instead of vanishing.

After

$ traj cat -r --raw --filter type=thought | jq -r .content
zebra
apple
mango
banana
yak

to_epoch has no other caller, and _sorted_tree_steps is reached only from
the -r branches of cmd_tail and cmd_cat, so nothing outside those two
paths changes. I put every timestamp shape in the tree through the old and the
new key: every input that previously produced a value keeps its exact relative
order (new = old × 1000 + ms). The only behaviour that changes is for the Z
and lowercase-z forms and the unparseable ones, which previously produced
nothing at all. The +0800 stamps in tests/fixtures/ take the capture()
branch and are untouched.

Worth saying plainly: nothing in the repo passes -r to traj — every
internal caller uses the single-file forms — so this fixes a documented,
advertised flag rather than an automated path. It changes what a person at a
terminal, or a model reading a sub-run, sees.

Tests

tests/test_traj_recursive_tree.sh has two parts.

Part A runs the real commands and leaves their stamps alone: six appends at
machine speed, which is the case a whole-second key gets wrong. It checks every
step on disk comes back, and comes back non-decreasing.

Part B builds a tree two levels deep with two branches out of the root, and
rewrites the stamps to defeat three wrong sort keys at once — every step but
one lands inside a single second, their alphabetical order differs from their
real one, and one sits in 1970 so its key is shorter than the rest. It pins the
interleaving, both levels and both branches of the recursion, both signs and
the minutes of the legacy offset, the third millisecond digit, --filter, the
per-file _traj_hex tag, tail -r -n bounding the merged stream rather than
one file, an unparseable stamp keeping its step, the formatted view a terminal
actually gets, and the non-recursive view staying as it was.

Red/green, by state of bin/traj:

bin/traj result
main 5 passed, 10 failed
Z fix only 7 passed, 8 failed
Z + catch, no milliseconds 9 passed, 6 failed
Z + milliseconds, no catch 13 passed, 2 failed
this branch 15 passed, 0 failed

I also mutation-tested it: 20 deliberate breakages of bin/traj — wrong sign,
dropped offset minutes, truncated milliseconds, lexical instead of numeric
sort, constant _traj_hex, recursion stopped at depth 1, only the first fork
per file followed, a per-file step cap, --filter ignored, and others — and
all 20 are caught.

Checked locally: tests/run-all.sh green apart from one pre-existing failure
unrelated to this change (test_persona_chat_exit.sh pins PATH to
/usr/bin:/bin, which has no jq on a Homebrew Mac, so identity new exits
127 — it fails the same way on main here, and is green in CI).
shellcheck -S warning clean over the CI file set, and the new test is clean
at -S info too. Parses and runs under Apple's bash 3.2; runs green under a
pure BSD userland and under GNU coreutils, which now agree on the order; stable
across timezones, across LC_ALL=C/en_US.UTF-8/de_DE.UTF-8, and over ten
consecutive runs. The bash-4-only construct grep is clean. cloc bin/ thinkers/ goes 9,912 -> 9,914 code lines against a limit of 11,000. pytest
green for web, slack and telegram.

`traj tail -r` and `traj cat -r` are the only readers in traj that sort steps,
and the key comes from to_epoch in _sorted_tree_steps. Three things were wrong
with it, all of them silent.

The catch-all branch — taken for any stamp that is not "<datetime><numeric
offset>" — kept the whole string as .dt, and the next line appends "Z" to
that. Every stamp traj writes is UTC and already ends in "Z" (_iso_ts), so
fromdateiso8601 was handed "2026-09-04T14:13:18ZZ" and errored on every step.
jq's stderr is discarded and its status is `|| true`, so both commands printed
nothing at all and still exited 0. Only steps still carrying the legacy
"+hh:mm" spelling survived, so a tree containing one came back as just that
one step. The strip also takes the RFC-3339 lowercase "z", and trailing
whitespace after it, which previously reached the parser malformed.

The key also floored to the second, because the fraction is stripped before
parsing. A trajectory writes many steps a second, so most keys tie and sort(1)
falls back to comparing whole lines — the JSON text. Fixing only the "Z" would
have traded an empty result for a plausible but wrong one: on a real tree
`tail -r -n 2` returned the third- and fifth-newest steps, and GNU and BSD
sort disagreed about which. The key is now integer milliseconds, folded into
the integer rather than left as a decimal so the numeric sort cannot depend on
the locale decimal point.

Finally, an unparseable stamp took its step out of the tree rather than
sorting it somewhere. Every other date read in the tree already guards that
(bin/chat, thinkers/_lib/common.sh, bin/thinkers, thinkers/responder/step);
this was the one call site that did not, which also left the function's own
`(.ts // .timestamp // "0")` fallback dead.

search -r and check -r walk the same files without to_epoch and were never
affected, so the halves of the same flag disagreed. to_epoch has no other
caller, and _sorted_tree_steps is reached only from the -r branches of
cmd_tail and cmd_cat, so nothing outside those two paths changes. Every stamp
shape that produced a value before produces the same relative order now.

tests/test_traj_recursive_tree.sh has two parts. The first runs the real
commands and leaves their stamps alone — six appends at machine speed, the
case a whole-second key gets wrong — and checks every step on disk comes back,
and comes back non-decreasing. The second builds a tree two levels deep with
two branches out of the root, and rewrites the stamps to defeat three wrong
sort keys at once: every step but one lands inside a single second, their
alphabetical order differs from their real one, and one sits in 1970 so its
key is shorter than the rest. It pins the interleaving, both levels and both
branches of the recursion, both signs and the minutes of the legacy offset,
the third millisecond digit, --filter, the per-file _traj_hex tag, `tail -r -n`
bounding the merged stream rather than one file, an unparseable stamp keeping
its step, the formatted view a terminal gets, and the non-recursive view
staying as it was.
@nickjalbert

Copy link
Copy Markdown
Contributor

LGTM thanks for the PR! Ubuntu smoke test CI job is being flakey (seemingly unrelated to this code) so merging. 🚢

@nickjalbert
nickjalbert merged commit ce2e6fb into laude-institute:main Sep 5, 2026
22 of 24 checks passed
@MaxFreedomPollard

Copy link
Copy Markdown
Contributor Author

I did a little digging, and I think this is the reason, cheers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants