fix(api): share concurrent HTTP shutdown result

[ryan-wong-coder]

Linked Issue

Fixes #13

Summary

• make the first bounded Fiber Shutdown caller the sole owner of the drain deadline
• make every later concurrent caller wait for and return the same stored terminal result
• cover both graceful completion and forced initiating deadline results with deterministic real-listener tests
• document the shared HTTP shutdown contract alongside the matching gRPC lifecycle rule

Required Format

• Branch name uses an approved prefix: feat/, fix/, docs/, test/, refactor/, perf/, security/, chore/, ci/, build/, release/, or revert/.
• PR title uses Conventional Commit style, for example fix(consensus): reject equivocated proposer slots.
• Commit messages use Conventional Commits.

Scope And Project Status

• This PR solves one issue or one clearly scoped maintenance task.
• This PR excludes unrelated formatting, experiments, generated files, local data, credentials, logs, captures, and build artifacts.
• User-facing material distinguishes implemented behavior, target design, and roadmap work.
• Any performance claim identifies its source, hardware, configuration, measurement method, and whether it is a FinalWeave result.

No performance claim is introduced.

Protocol, Safety, And Compatibility

• This PR does not change quorum, Byzantine fault, proposer-slot, stable-prefix, or epoch-transition rules.
• BatchAC still proves recoverable data availability only; it is not treated as transaction validity, ordering, or execution finality.
• Canonical ordering and speculative parallel execution remain deterministic and equivalent to canonical serial Apply.
• External finality remains bound to an authenticated Header, exact FinalityCertificate, locally trusted validator/config chain, and query-specific proofs.
• This PR does not change canonical encoding, domain separation, signatures, IDs, state commitments, or wire schemas.
• WAL, atomic publication, snapshots, pruning, synchronization, replay, and recovery preserve their durable safety boundaries.
• This PR does not change networking, admission, cross-ledger proof validation, or resource-accounting boundaries.
• No production path introduces unbounded scan, sort, load, verification, retry, amplification, or recomputation behavior.

This is a local lifecycle synchronization fix. The initiating caller still must provide a deadline and continues to bound the drain. Later callers cannot shorten, extend, or replace that operation; they only observe its stored terminal result. There are no runtime users or compatibility requirements.

Validation

• git diff --check
• python3 scripts/check_docs.py
• go mod verify and a clean go mod tidy diff
• go vet ./...
• go test -count=1 -mod=readonly ./...
• go test -race -count=1 -mod=readonly ./...
• python3 scripts/check_go_architecture.py
• Relevant unit, race, property, fuzz, vector, model, Byzantine, partition, crash-recovery, snapshot, chaos, and performance checks
• Negative tests cover malformed, conflicting, stale, replayed, oversized, and partially durable inputs where applicable

Additional focused validation:

• go test -count=30 ./pkg/api/httpserver
• go test -race -count=30 ./pkg/api/httpserver
• HTTP startup and concurrent graceful/forced shutdown stress tests with -race -count=100
• Linux amd64 and arm64 static builds with -trimpath

Protocol, storage, Byzantine, partition, snapshot, and chaos suites are not applicable because this change modifies only in-process operational HTTP shutdown coordination.

Risk And Rollback

Risk is limited to callers that intentionally expected their later private context to return before the already-running shutdown. That behavior contradicted the documented terminal-state contract and has no released users. The initiating deadline still guarantees a bounded outcome.

Rollback by reverting this commit; no data, schema, listener configuration, dependency, or migration is involved.