[adamant-pwn]

Second of four stacked PRs for labeled traversal, on #708.

This PR adds traverse_seed, which extends a seed through the graph and keeps, on each path, the labels that carry every k-mer walked. The labels are named, or taken from the seed: those on every seed k-mer. A seed that no label carries fails with SeedDerivationError, so a caller can report it for that seed alone. Each arm returns a tree of segments, one path per leaf, the reason each label left, and complete_to_bp: the length up to which every walk is present.

A path never reuses an edge or steps back into the seed, so walks end on graphs with cycles. A label that continues on several successors spends one of its max_label_branches (default 0). With none left, it ends there. Fixed caps bound the work: 1,000,000 steps and a time budget per seed, 1000 live paths and 10,000 paths per arm, and 64 splits per path. A cap marks the arm truncated.

test_walker_reference checks every label end against a string model of the test records.

Co-authored-by: Gunnar Rätsch

🤖 Generated with Claude Code

[cubic-dev-ai]

Review completed against the latest diff

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files

Architecture diagram

sequenceDiagram
    participant API as Traversal Service API
    participant Walk as traverse_seed()
    participant Oracle as LabelOracle
    participant Graph as DeBruijnGraph
    participant Anno as AnnotatedDBG
    participant WalkRule as Walker Engine
    participant Caps as Cap Manager
    participant Result as SeedResult

    Note over API,Result: Labeled Traversal Walker Flow

    API->>Walk: Request traversal with Seed + Strategy
    Walk->>Walk: validate_seed()
    alt Seed not in graph
        Walk-->>API: SeedNotInGraph error
    end

    Walk->>Oracle: Create LabelOracle(graph)
    Oracle->>Graph: Get k-mer size and alphabet
    Oracle-->>Walk: Oracle instance

    alt Explicit labels provided
        Walk->>Oracle: Check labels carry seed k-mers
    else Derive labels from seed
        Walk->>Oracle: Query annotations for seed k-mers
        Oracle->>Anno: Fetch label annotations
        Anno-->>Oracle: Label hits per k-mer
        Oracle-->>Walk: Derived label set
        alt No carrier label found
            Walk-->>API: SeedDerivationError (NO_CARRIER)
        end
    end

    Walk->>WalkRule: Initialize arms (LEFT/RIGHT per direction)
    WalkRule->>Graph: Get seed boundary k-mers
    Graph-->>WalkRule: Boundary nodes

    loop Walk level by level (max_extension_bp)
        WalkRule->>WalkRule: Generate successor candidates
        WalkRule->>Graph: Query successors for current k-mer
        Graph-->>WalkRule: Succ list with base chars

        WalkRule->>WalkRule: Apply walk rule per candidate
        Note over WalkRule: Check edge reuse, seed re-entry, hairpins

        WalkRule->>Caps: Check resource limits
        Caps-->>WalkRule: Status (OK or TRUNCATED)

        alt Cap exceeded
            WalkRule->>Result: Mark cap trigger + lower complete_to_bp
        else All caps fine
            WalkRule->>WalkRule: Split paths at label branches
            WalkRule->>WalkRule: Track label ends with reasons
            WalkRule->>Result: Extend segments and paths
        end

        alt Label criteria per branch
            WalkRule->>WalkRule: Filter successors by label carry
            WalkRule->>WalkRule: Apply branch allowance
            WalkRule->>WalkRule: End labels with DEAD_END/LABEL_LOST/BRANCH
        end
    end

    WalkRule->>Result: Build segment tree with splits
    Result->>Result: Record path ends and label ends
    Result-->>API: Complete SeedResult with arms

Loading

<sub>Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds the labeled traversal walker with reference tests; the decisive unresolved issue is cubic's dismissed P2 that non-finite time_budget_ms can disable the time-budget safety cap, with no fix visible in the diff.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds the labeled traversal walker with an independent reference model and caps; the decisive unresolved issue is the dismissed P2 that non-finite time_budget_ms can disable the time-budget safety cap, with no fix visible in the diff.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds the labeled traversal walker with an independent reference model and revised label discovery; the dismissed P2 that non-finite time_budget_ms can disable the time-budget safety cap is still not addressed in the visible diff.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds the labeled traversal walker with an independent reference test model. The dismissed P2 that NaN/infinite time_budget_ms can disable the TIME_BUDGET safety cap is still unaddressed, so accepting that risk needs human sign-off.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 6 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds the labeled traversal walker with bounded caps and an independent reference test. The dismissed P2 that NaN/infinite time_budget_ms can disable the TIME_BUDGET safety cap is still unaddressed, making acceptance of that safety-cap risk the decisive open question.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds the labeled traversal walker with bounded caps and an independent reference test. The decisive open issue is the safety cap: non-finite time_budget_ms can disable the TIME_BUDGET cap and no fix is visible, so accepting that risk needs human review.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>