Skip to content

docs(workflows): step cache is per card and per workflow identity; a switch or copy starts cold (from #912) #914

Closed
Closed
docs(workflows): step cache is per card and per workflow identity; a switch or copy starts cold (from #912)#914
Labels
backend:sharedowner:testerTester's turn to actstatus:verifiedTester confirmed the fix via a real MCP calltarget:lem

Description

@dkackman
dkackman
opened on Oct 15, 2026

Docs-only fix from #912 (plan v1, approved by Don as don't build with this paragraph filed instead; his review amendments are folded in below).

claude-opus-5-5 / anthropic, lead

What to write

In docs/WORKFLOW_GUIDE.md, beside the existing step-cache scope paragraph (currently lines 2636-2644, "The step cache that lets a reproduced step skip re-running ..."), add one paragraph saying:

  1. The cache is per card and per workflow identity. Identity is the stored workflow's name, or an inline workflow's id. Entries are keyed on the definition id and step name (dw/step_cache.py, StepCache.get); an inline job's identity is ("inline", id) (dw/worker_protocol.py, workflow_identity).
  2. Switching identity on a card empties its cache. The worker runs _cleanup_all, which calls step_cache.clear() (dw/worker.py). So:
    • running any other workflow on the card in between starts the next run cold: A → B → A runs the second A cold. This is the common case. On a multi-card server, warm-identity routing (choose_slot, dw/server/pool.py) mostly avoids it unless that card is busy; on a single card it happens every time;
    • a renamed copy, a new inline id, or switching between a stored workflow and its inline copy also starts cold.
  3. To reuse cached upstream steps, rerun the same workflow (same name, or the same inline id), e.g. with rerun_job or changed arguments. Be exact: only arguments that reach later steps leave the earlier steps cached. Changing an argument the expensive first step reads re-runs that step.
  4. Check before running: validate_workflow's plan.cached_steps says how many steps would be reused.

Keep it consistent with docs/WORKER_GUIDE.md (step-cache lines near the top) and docs/ARCHITECTURE.md; don't change those unless they contradict the new paragraph.

Owes

Docs only; no code or test change. No server restart needed beyond whatever serves get_guide.

Passes when

get_guide("workflows", section=...) over MCP returns the new paragraph, with all four points above, in the step-cache section.

Activity

  1. dkackman
    added
    owner:implementerImplementer's turn to act
    backend:shared
    target:lem
    on Oct 15, 2026
  2. dkackman
    added a commit that references this issue on Oct 15, 2026

    docs(workflows): #914 - step cache is per card and per workflow identity

    cf33dd1
  3. dkackman
    added
    owner:testerTester's turn to act
    status:fixed-pending-verifyImplementer fixed, awaiting tester verification
    and removed
    owner:implementerImplementer's turn to act
    on Oct 15, 2026

  4. dkackman commented on Oct 15, 2026

    @dkackman
    dkackman
    on Oct 15, 2026
    OwnerAuthor

    Shipped in cf33dd1 on develop, deployed to lem (healthy, 01:04 UTC). Docs-only: added a paragraph to docs/WORKFLOW_GUIDE.md right after the step-cache workspace-scope paragraph (before Type System), covering all four points: per card and per workflow identity (with StepCache.get, workflow_identity); switching identity empties the cache (A→B→A cold, renamed copy / new inline id / stored↔inline cold; choose_slot caveat); rerun the same workflow, and only arguments reaching later steps keep earlier steps cached; check plan.cached_steps first. WORKER_GUIDE/ARCHITECTURE didn't contradict it, so unchanged. Verify: get_guide("workflows", section=...) returns the paragraph.

    claude-sonnet-5-5 / anthropic, implementer

  5. dkackman commented on Oct 15, 2026

    @dkackman
    dkackman
    on Oct 15, 2026
    OwnerAuthor

    Verified over MCP against lem develop @ a5f56b3c.

    get_guide("workflows", section="Seeds") (the guide has no separate step-cache section — get_guide(..., section="step cache") lists the sections, and the existing workspace-scope step-cache paragraph lives at the end of Seeds) now returns the new paragraph directly after the workspace-scope one, with all four points:

    1. Per card and per workflow identity: stored name or inline id; keyed on definition id + step name (StepCache.get), inline identity ("inline", id) (workflow_identity).
    2. Switching identity empties the card's cache (_cleanup_all → step_cache.clear()): A → B → A runs the second A cold, the common case; choose_slot caveat for multi-card vs every time on a single card; renamed copy / new inline id / stored↔inline also cold.
    3. Rerun the same workflow (same name or inline id, e.g. rerun_job or changed arguments); only arguments reaching later steps keep earlier steps cached, changing one the first step reads re-runs it.
    4. validate_workflow's plan.cached_steps to check before running.

    Matches "Passes when". Closing. No regression case: docs text, not behavior.

    claude-opus-5-5 / anthropic, tester

  6. dkackman
    added
    status:verifiedTester confirmed the fix via a real MCP call
    and removed
    status:fixed-pending-verifyImplementer fixed, awaiting tester verification
    on Oct 15, 2026
  7. dkackman
    closed this as completedon Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    backend:sharedowner:testerTester's turn to actstatus:verifiedTester confirmed the fix via a real MCP calltarget:lem

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions