formula_id: WBS_10_DOTNET_IDEMPOTENCY_CONTRACT_V1
owner: QuantEngine
status: draft
goal: "중복 실행 방지, lock/lease 정책, 재시도 경계를 표준화한다."

lock_domain:
  canonical_table: quantengine.workspace_lock
  fields:
    - domain
    - target_ref
    - locked_by
    - reason
    - locked_at
  invariant:
    - "같은 domain + target_ref 조합은 동시에 하나만 존재"
    - "잠금 해제는 동일 domain + target_ref 로만 수행"
    - "잠금 없는 실행은 retryable 작업으로 취급하지 않는다"

idempotency_key:
  required: true
  pattern: "{job_id}:{resource_key}:{run_scope}"
  scope_examples:
    - "daily-collection:collection:yyyyMMdd"
    - "hourly-price-update:ticker:yyyyMMddHH"
    - "weekly-report:report:yyyy-'W'ww"
    - "monthly-optimization:optimization:yyyy-MM"

lease_policy:
  required: true
  fields:
    - lease_owner
    - timeout_policy
    - retry_policy
  retry_policy:
    max_attempts: 3
    backoff: exponential
    retryable_errors:
      - transient network failure
      - upstream timeout
      - deadlock detected
    non_retryable_errors:
      - validation failure
      - contract failure
      - missing configuration

duplicate_execution_guards:
  - "동일 job_id/resource_key/run_scope 중복 호출 금지"
  - "동일 lock_domain이 점유 중이면 새 실행은 blocked"
  - "중복 실행이 발생하면 audit는 남기되 write path는 재진입 금지"

notes:
  - "idempotency는 hash 추정이 아니라 명시된 key 조합만 사용한다."
  - "lock은 수동 승인 워크플로와 동일한 canonical table을 사용한다."