Files
insights/.claude/rules/temporal-workflow-versioning.md
zeekay 1b367e2b62 chore: rebase the tree onto upstream master
The tree was a debranded snapshot of upstream taken around 2026-02-20, and
upstream has moved about five months since. This replaces it with upstream
master, mechanically re-derived: bin/debrand does the rename, and the
pipeline and squashed migrations are restored from the shipped tree.

Not a merge. The previous import replaced the tree wholesale in a single
commit, so there is no shared content history to merge against. Reproducing
the rename on the new tree is what actually converges.

What survives: .hanzo/workflows, the Dockerfiles and bin/docker* entrypoints,
compose files, LLM.md, and insights/migrations. The squashed initial
migration is load-bearing — the live database records it by name, so
upstream's ~918 individual migrations cannot come back.

Nine products are dropped as unreferenced. Twenty-one more that we do not run
are kept anyway because the core app still imports them; unpicking those is a
refactor and does not belong in a rebase.

This base does not build yet, and the reasons are not in the rename:
upstream now wants Python 3.13.13 against our 3.12.12 and Django 5.2 against
our 4.2, and the dependency manifests still name upstream packages that we
republish under our own names. Those are decisions, not renames.
2026-08-01 15:44:40 -07:00

1.6 KiB

paths
paths
insights/temporal/**
products/*/backend/temporal/**

Editing a @workflow.defn body (adding/removing/reordering execute_activity, child-workflow starts, or timers) breaks in-flight executions with "Non Deterministic Error" — on deploy every running execution replays its recorded history against the new code, and any new unconditional command at a point an execution already passed fails the replay. Activity implementations and activity input dataclasses are safe to edit; workflow command sequences are not.

When adding a new activity or child-workflow start to an existing workflow, gate it one of two ways:

  1. if workflow.patched("my-change-2026-07"): ... — the default. Old histories skip the block, new executions record a marker and run it. Precedent: insights/temporal/ai_observability/run_evaluation.py. Once no pre-patch executions remain (days, for short-lived workflows), optionally swap to workflow.deprecate_patch(...) + unconditional code.
  2. Gate on a new field of an existing activity's output dataclass that defaults to the skip value (e.g. enrichment_needed: bool = False in create_job_model.py) — old histories decode the missing field to the default, so the new command never fires during replay. Only valid when the decision comes from recorded history and skipping is acceptable for in-flight runs.

Never gate workflow commands on values computed inside the workflow body (feature flags, settings, clock, DB reads) — that is itself non-deterministic. Removing/reordering existing commands needs workflow.patched() with the old path kept in the else branch.