Skip to content

fix(crew-log): fold the timeline over one succession unit, not a slot of them - #15852

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/timeline-fold-single-unit-15591
Oct 1, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/timeline-fold-single-unit-15591

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Stop the crew-log timeline fold from silently rendering two succession units as one scrambled timeline.

The timeline fold (crew_log/projection.py) appends every moment and orders by
bare timestamp. A slot-wide read (fold_slot_checkpoint) folds the units a slot
ran under back to back, re-basing the seq per unit so the second unit restarts at

  1. Fold two units into one timeline and their moments interleave by wall clock, so
    a clock rollback between units inverts their order — the same latent defect the
    usage fold carries. Reproduced before the fix: folding timeline over two units
    yields moment seqs [1,2,3,4,5,1,2,3,4,5].

Why it matters

Nothing folds timeline over a slot today: it reaches readers only through a
single session's log (fold_session), and one session holds exactly one
succession unit. So this is a guard, not a live bug. But the day a slot-keyed
reader folds timeline over a slot — a slot-wide activity view, a crew-level
timeline — it inherits the inversion silently, because nothing in the fold rejects
a multi-unit input.

Not a goal

What changed (motivation → approach → change)

Symptom: a slot-wide timeline fold concatenates succession units into one list
whose seqs restart per unit, so a reader ordering by timestamp inverts units on a
clock rollback. Root cause: _timeline_step appends every moment and holds no
notion of the unit boundary. Change:

  • _timeline_start seeds last_seq (the seq of the newest moment folded, 0
    before the first).
  • _timeline_step raises CrewLogError(field="seq") when a moment arrives at a
    seq at or below last_seq — the mark that a second unit's seq restart has begun
    — instead of appending it.
  • The fold state carries last_seq now, so its state_version is bumped
    (_FOLD_STATE_VERSION_BASE + 1) to retire savepoints written in the old shape;
    the recorded pin in test_crew_log_checkpoint.py is updated.

The single-session path (the only reader today) is unchanged: within one unit the
seq only ever climbs, so the guard never fires.

Backwards compatibility

Compatible: the only reader today folds a single session (one succession unit),
where the seq only ever climbs, so the new guard never fires. The guard adds a
refusal on an input path (multi-unit slot fold) that no caller takes yet. The
state_version bump retires existing timeline savepoints to a cold refold —
a one-time recompute, not a behavior change.

Tests

  • test_timeline_folds_one_session_unaffected_by_the_single_unit_guard — the
    reachable single-session path renders every moment as before.
  • test_timeline_refuses_rows_from_a_second_succession_unit — one unit folds
    cleanly; the join of a second raises CrewLogError(field="seq").
  • Updated the timeline pin in
    test_changing_what_a_fold_stores_forces_the_savepoint_version_to_move.
  • Full test_crew_log_projection.py, test_crew_log_slot_folds.py,
    test_crew_log_checkpoint.py, test_crew_log_fold_eager.py,
    test_fold_catalogue.py green. black(py312)/isort/flake8/mypy and the
    comment-history gate clean.

Manual verification

N/A — unit coverage is sufficient: the guard is a pure fold-state invariant with a
test exercising both the single-unit (pass) and multi-unit (raise) paths.

Related Issues

Fixes #15591

Pattern harvest

Rule candidate: review-prompt
Pattern: a fold that concatenates per-unit logs must reject (or succession-order)
multi-unit input rather than trust a per-unit seq/timestamp as if it were global.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

N/A — placeholder; CLA wording to be supplied by OSPO.

… of them

The timeline fold appends every moment and sorts by bare timestamp, and a
slot-wide read folds the units a slot ran under back to back with each unit's
seq restarting at 1. Fold two units into one timeline and their moments
interleave by wall clock, so a clock rollback between units inverts their
order -- the same latent defect the usage fold has.

Nothing folds timeline over a slot today: it reaches readers only through a
single session's log, and one session holds exactly one succession unit. So
this is a guard, not a live bug. The day a slot-keyed reader folds timeline
over a slot, it inherits the inversion silently because nothing in the fold
rejects a multi-unit input.

The timeline fold now tracks the seq of the newest moment and raises when a
moment arrives at or below it -- the mark of a second unit's seq restart --
so a future slot-keyed reader fails loudly at the unit boundary instead of
rendering a scrambled timeline. The fold state carries last_seq now, so its
state_version is bumped to retire savepoints written in the old shape.

Fixes kirodotdev#15591
@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 1, 2026 12:31
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 0868b75c926219e62606048554bb3a85e9eca9e8 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 0868b75

Description read

[DESCRIPTION-READ] 1ddcb4e741346de5c293248ff1cea51474bfaed4840db05392ac69539bc2891b

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 0868b75c926219e62606048554bb3a85e9eca9e8 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- src/kiro_crew/crew_log/projection.py:1607 -- the invariant at <= lacks an equality mutation pin; changing it to < leaves the added tests green -> Fix: make the boundary test exercise a 1→1 restart.
[GPT-REVIEWED] 0868b75

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 0868b75c926219e62606048554bb3a85e9eca9e8 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The guard re-implements advance's existing at-or-below-seq refusal inside persisted fold state; one check at the join site covers all seven session folds with no savepoint retirement.

Not justified as shipped

  • Item 1 — duplicate of advance (src/kiro_crew/crew_log/projection.py:498): advance already refuses "entry at or below the checkpoint's seq" with the same CODE_BAD_DATA/field="seq"; the hazard exists only because fold_slot_checkpoint (projection.py:3099) re-bases past that guard for every fold, including the seven session-keyed ones (SESSION_FOLD_NAMES, projection.py:165). Grepped production callers of fold_slot_checkpoint|fold_slot|read_slot_projection: 4 sites, all slot-fold names — zero reach the guarded path, as the description concedes. Skipping the re-base (or refusing) for session-keyed names at that one site fires the existing refusal for all seven folds, leaving zero unguarded siblings instead of five (status, tools, approvals, subagents, class), and needs no new state. The description weighs only the issue's option 1; this smaller placement was never considered.
    Subtraction: delete last_seq from _timeline_start, the _timeline_step raise, and the state_version bump; in fold_slot_checkpoint, re-base only for SLOT_PROJECTION_NAMES so advance's refusal fires at the second unit.
    Clears when: the join-site placement is made, or crew-log: guard the timeline fold against the succession inversion usage just fixed #15591/feat(crew-log): serve the Context panel from the usage fold #15367 records why the guard must live per-fold rather than at the join.

What this change ships

Inventory (3 items) — 1 justified

Intent: make a future slot-wide read of the timeline fail loudly at a succession-unit boundary instead of silently concatenating units — a preventive guard (declared as such), not a live-bug FIX.

  1. A multi-unit timeline fold now raises CrewLogError at the second unit's seq restart — duplicate of advance (projection.py:498); see above.
  2. Every stored timeline savepoint is retired and refolds once (state_version bump) — rides along: cost of item 1's in-state placement, declared.
  3. Fold-state pin for timeline updated to the new version — justified.

[FIRST-PRINCIPLES-REVIEWED] 0868b75

Description read

[DESCRIPTION-READ] 8f899a5731617d290272b8ffb34cc5789bf16172a607e329d5ac81da13e7faf6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 0868b75c926219e62606048554bb3a85e9eca9e8 via the fork AI-review pipeline; updated in place on each push.

Review details

Nothing blocks; one advisory finding.

FINDING — test/test_crew_log_checkpoint.py:208 — the block comment above the table (line 203: it stands one past the base, and every sibling stays at 4, line 198: Every pair stands at 4) is the repo's only narration of when a state_version bump is owed, and the changed pair "timeline": ("4f461179faff39a3", 5) falsifies it, so a later author reading it concludes no sibling has ever moved → Fix: in this commit, restate the paragraph as which folds stand where (subagents at base+2, timeline at base+1, the rest at base) instead of a single number.

[OPUS-REVIEWED] 0868b75

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 1, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. fold_timeline carries last_seq and raises CrewLogError(CODE_BAD_DATA) when a moment's seq is at or below it, i.e. a second succession unit; the state version is bumped so an old savepoint is retired; the checkpoint hash pin is updated. One session holds one unit so the reachable path is unchanged (test pins it) and the guard case is pinned.

@iamwhatever
iamwhatever enabled auto-merge (squash) October 1, 2026 15:59
@iamwhatever
iamwhatever merged commit 0e399c4 into kirodotdev:main Oct 1, 2026
106 of 107 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

crew-log: guard the timeline fold against the succession inversion usage just fixed

2 participants