clarify workflow identity semantics and start idempotency model

[maxcountryman]

Summary

Workflow identity semantics are currently ambiguous: workflow_id is used like a run/execution identifier in several places, while product expectations may treat it as a stable logical workflow identifier.

We also do not have an explicit workflow start idempotency key API today (existing concurrency_key and activity call_key do not provide the same contract).

Why this matters

• Behavior can be surprising around restarts and scheduled dispatches if workflow_id is not stable.
• Cancellation/query semantics are unclear (cancel one execution vs all executions for a logical workflow).
• It is difficult to design durable API guarantees without explicit identity layers.

Current observations

• No dedicated start idempotency key API for workflows.
• workflow_id is embedded in workflow task input and used for activity call correlation.
• concurrency_key is a queue/task scheduling constraint, not a durable workflow-instance identity contract.

Proposed direction

1. Decide and document identity layers:
   • logical workflow identity (stable across runs) vs
   • workflow run identity (unique per execution).
2. Define API/behavioral semantics for:
   • enqueue/start,
   • cancel,
   • lookup/query,
   • scheduled dispatches.
3. Decide if explicit start idempotency keys should be added (and duplicate behavior policy).
4. Add tests and docs to enforce the chosen contract.

Acceptance criteria

• A documented identity model exists and is reflected in code/docs.
• Workflow start/cancel semantics are unambiguous.
• If idempotent starts are in scope, API and DB constraints support them with tests.

Related

• scheduled runs reuse workflow_id and can collide activity call keys #126
• tracking: p0 correctness hardening #137
• regenerate workflow ids from scheduled templates #138

[maxcountryman]

Opened PR #141 to introduce workflow run ID naming and schema updates (with legacy payload compatibility).