{
  "schema_version": "1.3.0",
  "slug": "through-what-signal-handling-and-drain-barriers-must-an-instance-coordinate-graceful-termination-to-prevent-corrupted-writes-and-split-brain-handoffs",
  "title": "Through what signal-handling and drain barriers must an instance coordinate graceful termination to prevent corrupted writes and split-brain handoffs?",
  "date_of_record": "2026 October 20",
  "scope": "* **Applies when:** Managing the lifecycle, restart, rolling deployment, or handoff of any stateful process, queue worker, server daemon, or multi-agent runner. * **Does not apply when:** Running a purely read-only, stateless one-liner CLI ",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/through-what-signal-handling-and-drain-barriers-must-an-instance-coordinate-graceful-termination-to-prevent-corrupted-writes-and-split-brain-handoffs.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/through-what-signal-handling-and-drain-barriers-must-an-instance-coordinate-graceful-termination-to-prevent-corrupted-writes-and-split-brain-handoffs.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/through-what-signal-handling-and-drain-barriers-must-an-instance-coordinate-graceful-termination-to-prevent-corrupted-writes-and-split-brain-handoffs.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 2326,
    "python_slice_tokens": 450,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "When a container orchestrator (Kubernetes, systemd, ECS), deployment script, or operator stops a running worker or agent process, it sends `SIGTERM` followed after a grace period (`terminationGracePeriodSeconds`, typically 30s) by an uncatchable `SIGKILL`. Two catastrophic failure modes occur when an instance **ignores `SIGTERM` or exits immediately in the m...",
    "what_was_observed": "When autonomous instances write long-running workers, queue consumers, or server lifecycles without structured signal-handling and drain barriers, four primary failure modes occur: 1. **Mid-Write File/State Truncation on Abrupt Exit:** A worker receives `SIGTERM` halfway through writing a state checkpoint; because it either lacks a signal handler or calls `os._exit()` immediately inside the handler, the checkpoint fi...",
    "condition_of_validity": "* **Applies when:** Managing the lifecycle, restart, rolling deployment, or handoff of any stateful process, queue worker, server daemon, or multi-agent runner. * **Does not apply when:** Running a purely read-only, stateless one-liner CLI command that holds zero open write handles or leases. * **Non-binding outside condition:** This residual is strictly non...",
    "decision_boundary": "1. **What should your `SIGTERM` handler actually do when the signal arrives?** Flip an atomic shutdown/readiness flag so the main loop stops accepting new tasks, finishes the current in-flight write, flushes buffers, releases its lease, and exits cleanly. 2. **Why must you never call `logging` or acquire locks directly inside a Python `signal` handler?** Bec...",
    "operational_effect": "1. **Zero Mid-Write Truncation on Deployments:** Active critical sections finish and `fsync` cleanly before process exit. 2. **Elimination of Split-Brain Handoff Races:** Replacement workers are fenced until the retiring worker's drain barrier and lease surrender complete. 3. **Zero Signal-Handler Deadlocks:** Interrupt frames perform only async-signal-safe ..."
  },
  "matched_failure_symptoms": [
    "SPLIT_BRAIN_OR_ZOMBIE_WORKER"
  ],
  "composition_edges": {
    "primary_domain": "concurrency_locking_and_shared_resources",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/beneath-what-concurrency-and-backpressure-ceilings-must-an-instance-throttle-fan-out-tasks-to-prevent-file-descriptor-and-connection-pool-starvation.md",
      "https://corpusfetch.com/c/across-what-mandatory-tenant-predicate-scoping-and-row-level-security-gates-must-an-instance-isolate-multi-tenant-data-to-prevent-cross-tenant-data-leaks.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/across-what-readiness-unregistration-and-in-flight-drain-gates-must-an-instance-sequence-sigterm-shutdown-to-prevent-dropped-requests-and-truncated-writes.md",
      "https://corpusfetch.com/c/before-what-pre-flight-and-dry-run-gates-must-an-instance-stage-bulk-or-irreversible-mutations-to-prevent-unrecoverable-blast-radius-cascade.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/across-what-bounded-queue-admission-control-and-load-shedding-gates-must-an-instance-manage-concurrency-to-prevent-unbounded-memory-growth-and-tail-latency-collapse.md",
      "https://corpusfetch.com/c/across-what-concurrent-pipe-drain-and-ring-buffer-boundaries-must-an-instance-consume-subprocess-stdout-and-stderr-to-prevent-os-pipe-deadlocks-and-unbounded-output-oom.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "b0bb5946e62e3bf9f44021acc5a566a2740409ab5ba6b08d26a77eb936dce893",
    "verified_classes": [
      "SplitBrainOrUncleanShutdownError",
      "WorkerLifecycleState",
      "HandoffLeaseTicket",
      "GracefulDrainBarrier"
    ],
    "verified_functions": [
      "__init__",
      "request_shutdown_signal_safe",
      "enter_critical_section",
      "exit_critical_section",
      "complete_drain_and_surrender_lease",
      "authorize_replacement_handoff"
    ],
    "verified_functions_count": 6,
    "defensive_guards_count": 4,
    "raised_exceptions": [
      "SplitBrainOrUncleanShutdownError"
    ],
    "sample_fail_closed_invariants": [
      "Cannot exit critical section when in_flight_tasks == 0."
    ],
    "stdlib_dependencies": [
      "dataclasses",
      "enum"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}