Fix audit findings (non-docs): spec-conformance, bugs, security, refactor

[nficano]

Summary

Fixes the non-docs audit findings across arcp-core, arcp-runtime, arcp-client, and the middleware adapters: spec-conformance gaps, security leaks, resource/lifecycle bugs, a high-severity resume bug, and a partial refactor of SessionLoop. All modules build and mvn test is green (run with -Darcp.skip.spotless=true locally on JDK 25, per the pom note; CI runs Spotless on JDK 21).

Spec-conformance

• Fixes Lease-expiry termination emits final_status "timed_out" instead of "error" with LEASE_EXPIRED (§9.5 / §7.3) #74 Lease-expiry termination now emits final_status: "error" with LEASE_EXPIRED (terminal status ERROR).
• Fixes max_runtime_sec is accepted but never enforced; TIMEOUT is never produced (§7.1 / §12) #89 Enforce max_runtime_sec via a watchdog that emits TIMEOUT / final_status: "timed_out"; both watchdogs are cancelled when the job ends.
• Fixes Failed accept permanently poisons the idempotency key; identical retry gets DUPLICATE_KEY (§7.2) #90 Failed accept releases the idempotency claim, so an identical retry is accepted (or re-rejected with the original error) instead of being poisoned with DUPLICATE_KEY.
• Fixes Idempotency fingerprint is not canonical: JSON key order in input changes the SHA-256 (§7.2) #91 Idempotency fingerprint sorts ObjectNode properties, so key-order-only differences hash identically.
• Fixes Subscription fan-out forwards the producer's event_seq into the subscriber stream (§7.6 / §8.3) #76 Forwarded subscriber events use the subscriber session's own event_seq space.
• Fixes Invalid (non-UTC / malformed) job.submit silently dropped instead of INVALID_REQUEST (§9.5 / §12) #78 Undecodable/invalid job.submit (e.g. non-UTC expires_at) now returns INVALID_REQUEST instead of being silently dropped.
• Fixes Idempotent replay returns current remaining budget, not the original job.accepted budget (§7.2) #79 Idempotent replay returns the budget captured at acceptance.
• Fixes Cross-session subscribers never receive job.result / job.error (§7.6) #93 Terminal job.result / job.error fan out to subscriber sessions (with their own seq, no credentials).
• Fixes job.cancel is never acknowledged: no job.cancelled message exists, and invalid cancels are silently dropped (§7.4) #95 Adds job.cancelled ack; cancel of an unknown/invisible job returns JOB_NOT_FOUND, missing job_id returns INVALID_REQUEST — no silent drops.
• Fixes Session close uses session.bye and never acknowledges; spec requires session.close / session.closed (§6.7) #96 Adds session.close / session.closed (with session.bye accepted as a deprecated alias) and acknowledges before teardown.
• Fixes Unknown credential scheme throws during decode, dropping the whole job.accepted and hanging the submitter (§9.8.1) #97 Unknown credential scheme decodes to UNKNOWN instead of throwing; the client ignores unrecognized-scheme credentials, so a single extension credential can no longer deadlock the submit path.
• Fixes SessionLoop.handleListJobs materializes and sorts all matches before slicing #83 list_jobs only materializes JobSummary for the requested page.
• Fixes Lease delegation subsetting (§9.4 / §10) is unimplemented; Lease.contains and LEASE_SUBSET_VIOLATION are dead code #77 Lease.contains compares cost.budget numerically; adds a LeaseSubset validator for delegation subset enforcement (capabilities, numeric budget, model.use, expiry) throwing LEASE_SUBSET_VIOLATION. (Partial — see Notes.)
• Fixes Agent-emitted cost.budget.remaining gauges are treated as spend and decrement the budget (§9.6) #108 cost.budget.* gauges are no longer treated as spend; null metric values are guarded.

Security

• Fixes credential_rotated event carrying the credential value is fanned out to subscribers (§14) #75 credential_rotated is delivered only to the submitting session, never fanned out to subscribers.
• Fixes job.subscribe history replay forwards raw producer-session envelopes — wrong session_id, foreign event_seq, and replayed credential_rotated secrets (§7.6 / §8.3 / §14) #94 Subscribe-history replay re-envelopes events with the subscriber's session_id and freshly allocated event_seq, and never replays credential material to a non-owning subscriber.
• Fixes rotateCredential leaks extra provisioned credentials and can revoke the rotated credential's own provider handle (§9.8.2 / §14) #98 rotateCredential records/revokes surplus minted credentials and fails loudly on an empty issue rather than aliasing (and then revoking) a live handle.
• Fixes allowedHosts is dead configuration in ArcpJettyServer and the Spring Boot middleware #99 allowedHosts is enforced (Jetty servlet filter + Spring HandshakeInterceptor) returning 403 before the upgrade, instead of being a silently ignored knob.
• Fixes Jakarta adapter "rejects" disallowed hosts by clearing response headers — server still accepts the session #100 The Jakarta adapter records the host decision per handshake and closes the session with VIOLATED_POLICY before ArcpRuntime.accept, instead of merely clearing response headers (which the container ignores).

Bugs / lifecycle

• Fixes Resume reconnects start fresh sessions and cancel in-flight jobs #22 Implements session resume: an unexpected transport drop parks the session for the resume window (jobs kept alive, events buffered); a valid resume_token reattaches the new transport to the same identity, replays missed events, and continues live delivery. Explicit session.close still cancels. Unknown/expired tokens return RESUME_WINDOW_EXPIRED.
• Fixes runJob catch blocks emit a second terminal job.error after cancel/expiry already terminated the job #92 runJob catch blocks guard terminal emission so a job can never emit two terminal messages.
• Fixes Runtime memory grows without bound: JobRecord.eventHistory is unlimited and terminal jobs are never evicted #101 Per-job event history is bounded (resume-buffer capacity), terminal jobs are evicted after the resume window, and closed sessions are unlinked from subscriber lists.
• Fixes Client fails an unrelated pending submit when a top-level job.error arrives for list_jobs/subscribe failures #102 Top-level errors echo the originating request id; the client correlates them, so a list_jobs/subscribe error never fails an unrelated in-flight submit and listJobs surfaces its own INVALID_REQUEST instead of timing out.
• Fixes doHandshake can resurrect a CLOSED session (phase.set(ACTIVE)) and leak a never-cancelled heartbeat task #103 Handshake uses compareAndSet and a volatile heartbeat handle, so a closed session cannot be resurrected and no orphaned heartbeat task leaks.
• Fixes Lease-expiry watchdog can fire before setWorker, losing the interrupt; cancelled() ignores TIMED_OUT so the agent never stops #104 The worker is started before the watchdog is scheduled, and cancelled() covers all terminal states, so a polling agent exits after lease-expiry termination.
• Fixes ArcpClient never completes subscribe() publishers when the job reaches a terminal state #105 The client completes (onComplete/onError) live subscribe() publishers when the job terminates and releases per-job executors.
• Fixes ArcpClient.submit blocks indefinitely with join() and deadlocks when called from a completion callback #106 Blocking submit is bounded by a configurable timeout and fails fast if called from a dispatch/result callback; adds submitAsync.
• Fixes ArcpRuntime.accept registers the session after start(), racing transport completion into a zombie map entry #107 ArcpRuntime.accept registers the session before start() to avoid a zombie map entry on synchronous transport completion.
• Fixes Vert.x transport send is fire-and-forget: write failures are silently lost, so the runtime never detects a dead session #110 The Vert.x transport observes the async write result and fails the transport on write error instead of silently dropping events.
• Fixes ResultStream silently overwrites duplicate out-of-order chunks it claims to reject (§8.4) #111 ResultStream rejects divergent duplicate pending chunks (tolerating byte-identical retransmissions).

Refactor / testing

• Fixes SessionLoop.java exceeds the file-length threshold (922 > 800 LOC) #80, Fixes SessionLoop is a 922-line transport, protocol, lifecycle, and credential coordinator #82 (partial) Extracts IdempotencyFingerprint and JobListing from SessionLoop into cohesive, separately-tested types; SessionLoop no longer contains the list-jobs implementation. The full job-execution/submit/subscribe extraction and the <800-line target are deferred to keep this PR's behavioral changes low-risk.
• Measured JaCoCo coverage is far below the 80 percent target #33 (opportunistic) Adds protocol/unit tests alongside the fixes (SessionLoopAuditTest, SessionResumeTest, ClientAuditTest, LeaseSubsetTest, IdempotencyFingerprintTest, JobListingTest, plus extensions to existing tests). No JaCoCo threshold change.

Notes / partial

• Lease delegation subsetting (§9.4 / §10) is unimplemented; Lease.contains and LEASE_SUBSET_VIOLATION are dead code #77 The numeric/temporal subset logic and a LeaseSubset validator are implemented and tested, but end-to-end runtime auto-enforcement is not wired because this SDK uses client-driven manual delegation (the runtime does not derive child leases from DelegateEvent, which carries no lease). The validator is ready for a future delegate-request flow.
• Credential issuance join() blocks the session dispatch thread, starving heartbeats and all other messages #109 (async credential issuance during accept) is intentionally not changed: making accept asynchronous would break the client's FIFO job.accepted correlation without a per-session sequencing layer; deferred to avoid that regression risk. The blocking issue().join() remains.

Test plan

• mvn -DskipTests -Darcp.skip.spotless=true install
• mvn -Darcp.skip.spotless=true test (all modules green; one pre-existing-style timing flake in SubscribeReplayTest is auto-reran green by the repo's surefire config)
• CI Spotless/format check on JDK 21

Summary by CodeRabbit

Release Notes

• New Features

  • Sessions can now be automatically parked and resumed when transport connections unexpectedly drop, allowing clients to reconnect and replay missed events.
  • Added host allowlisting for enhanced security control over WebSocket connections.
  • Job listings now support cursor-based pagination.
  • Introduced configurable timeout for blocking job submission operations.

• Bug Fixes

  • Improved handling of transport write failures and connection termination.
  • Enhanced duplicate chunk detection and rejection.
  • Better error handling for unknown credential schemes.

• Tests

  • Added comprehensive test coverage for session resumption, job lifecycle, pagination, and credential handling.

[coderabbitai]

Warning

Review limit reached

@nficano, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 29 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2247ce10-b599-4bbb-9035-563447edcf8d

📥 Commits

Reviewing files that changed from the base of the PR and between 5e0e13d and 5ef793a.

📒 Files selected for processing (1)

• arcp-runtime/src/main/java/dev/arcp/runtime/session/SessionLoop.java

📝 Walkthrough

Walkthrough

This PR implements session resume resilience, credential scheme flexibility, host allowlist security, and idempotent job submission. The changes span message protocol extensions, client-side blocking behavior with timeout, lease delegation validation, bounded event history, idempotency fingerprinting, session parking across unexpected transport drops, and host validation across multiple middleware frameworks.

Changes

Session Resume, Resilience, and Credential Security

Layer / File(s)	Summary
Message Protocol Extensions & Credential Scheme Flexibility arcp-core/src/main/java/dev/arcp/core/messages/*, arcp-core/src/main/java/dev/arcp/core/credentials/CredentialScheme.java, arcp-core/src/test/java/dev/arcp/core/*	SessionClosed and JobCancelled message records added to sealed Message interface. Message.Type enum gains SESSION_CLOSED and JOB_CANCELLED discriminators; SESSION_BYE wire value updated to session.close with legacy session.bye mapping for backward compatibility. CredentialScheme introduces UNKNOWN constant and changes fromWire to return UNKNOWN instead of throwing for unrecognized schemes. Messages.decode extended to handle new message types. All message kinds round-trip tested.
Lease Subset Delegation Validation arcp-core/src/main/java/dev/arcp/core/lease/Lease.java, arcp-core/src/main/java/dev/arcp/core/lease/LeaseSubset.java, arcp-core/src/test/java/dev/arcp/core/lease/*	New LeaseSubset utility enforces strict delegation constraints: validates child namespace presence in parent, special-cases cost.budget with per-currency numeric amount comparison (not glob patterns), checks non-budget pattern coverage via Lease.contains, and validates temporal expiry constraints. Lease.contains extended to branch on cost.budget namespace. Tests verify budget subset enforcement, valid delegation, and constraint violations.
Job Event History Redesign with Idempotency arcp-runtime/src/main/java/dev/arcp/runtime/session/JobRecord.java, arcp-runtime/src/main/java/dev/arcp/runtime/idempotency/IdempotencyFingerprint.java, arcp-runtime/src/main/java/dev/arcp/runtime/idempotency/IdempotencyStore.java, arcp-runtime/src/main/java/dev/arcp/runtime/session/JobListing.java, arcp-runtime/src/test/java/dev/arcp/runtime/*	JobRecord replaces unbounded envelope history with bounded deque of RecordedEvent entries (producerSeq + JobEvent), enforces DEFAULT_HISTORY_CAPACITY=1024 via FIFO eviction, adds watchdog and budget snapshot storage. IdempotencyFingerprint canonicalizes JobSubmit JSON (sorted keys, exact decimals), computes SHA-256 digest. IdempotencyStore.release() conditionally removes stale idempotency claims. JobListing provides pagination with Base64-url cursor encoding, deterministic sorting, and filter support. Tests cover fingerprint key-order invariance, cursor handling, pagination, and audit scenarios.
Client-side Blocking Submit with Timeout & Error Correlation arcp-client/src/main/java/dev/arcp/client/ArcpClient.java, arcp-client/src/main/java/dev/arcp/client/ResultStream.java, arcp-client/src/test/java/dev/arcp/client/*	ArcpClient.Builder exposes submitTimeout(Duration). Blocking submit(jobSubmit, traceId) forbids execution from dispatch thread (via inDispatch ThreadLocal), waits for job.accepted using Future.get with timeout, removes pending-submit on timeout, normalizes failures to IllegalStateException. submitAsync returns future directly (no blocking). handleError rewritten to correlate top-level errors to listJobs via envelope id or pending submits. handleAccepted filters credentials via withRecognizedCredentials to exclude unknown schemes. completeLiveSubscriber helper ensures consistent subscriber shutdown. ResultStream adds duplicate chunk detection: tolerates byte-identical retransmissions, rejects divergent duplicates. Tests verify live subscriber completion, async resolution, cross-session subscription, and unknown resume token rejection.
Host Allowlist Security Across Frameworks arcp-middleware-spring-boot/src/main/java/dev/arcp/middleware/spring/*, arcp-middleware-jakarta/src/main/java/dev/arcp/middleware/jakarta/*, arcp-runtime-jetty/src/main/java/dev/arcp/runtime/jetty/*, arcp-middleware-vertx/src/main/java/dev/arcp/middleware/vertx/VertxWebSocketTransport.java, .github/workflows/ci.yml	Spring Boot adds HostAllowlistHandshakeInterceptor WebSocket interceptor returning 403 for disallowed hosts. Jakarta refactors rejection via ThreadLocal bridge in modifyHandshake/getEndpointInstance to spec-compliant early termination in ArcpJakartaEndpoint.onOpen. Jetty adds HostAllowlistFilter servlet filter blocking disallowed hosts before upgrade, installed on root context for REQUEST dispatcher type. Vert.x improves reliability with async failure callback on writeTextMessage, surfacing write errors. CI Maven command updated to run package before javadoc:javadoc for inter-module resolution.
SessionLoop Resume Support with Parking & Event Buffering arcp-runtime/src/main/java/dev/arcp/runtime/session/SessionLoop.java, arcp-runtime/src/test/java/dev/arcp/runtime/SessionLoopAuditTest.java, arcp-runtime/src/test/java/dev/arcp/runtime/SessionResumeTest.java	SessionLoop adds Phase.PARKED state, volatile transport field, parkExpiry/explicitClose/resumeDelegate/heartbeatInterval fields. Transport errors route through onTransportDropped(reason): unexpected drops park if resumable; explicit close shuts down. Handshake enhanced to reattach parked sessions, replay buffered events, reschedule heartbeat via resumeOnto(...)/rejectResume() helpers. Message dispatch handles SessionClosed/JobCancelled as client-only, correlates errors to envelopes. handleListJobs uses JobListing.page(...) for pagination. Idempotency uses IdempotencyFingerprint.of(mapper, submit) with stale-claim release/reclaim on retry. Job events recorded with per-subscriber seq allocation, credential_rotated redacted for non-owners. sendWithId(...) buffers sequenced messages; while PARKED, messages buffered instead of sent. Comprehensive audit and resume tests.
ArcpRuntime Resume Session Management arcp-runtime/src/main/java/dev/arcp/runtime/ArcpRuntime.java	New resumable map (concurrent, token-keyed) stores parked SessionLoop instances. Public APIs: parkResumable(token, loop), takeResumable(token), removeResumable(token, loop) conditionally removes only if loop matches. accept(Transport) inserts loop into sessions before calling start(), removes if start results in CLOSED phase (prevents zombie entries). close() shuts down all parked sessions and clears resumable registry before active-session cleanup.
Credential Revocation & Resume Examples arcp-runtime/src/main/java/dev/arcp/runtime/credentials/CredentialBinding.java, examples/resume/src/main/java/dev/arcp/examples/resume/Main.java, recipes/stream-resume/src/main/java/dev/arcp/recipes/streamresume/Main.java	CredentialBinding.revokeMinted(IssuedCredential) records credential identity in revocation store before delegating to internal revocation. Examples explicitly model transport drop, capture resume token/sequence, wait for PARKED phase, reconnect with saved token/sequence for history replay. Demonstrates fault-tolerant session lifecycle with parking vs. explicit-close semantics.
ResultStream Duplicate Chunk Idempotency arcp-client/src/main/java/dev/arcp/client/ResultStream.java, arcp-client/src/test/java/dev/arcp/client/ResultStreamTest.java	ResultStream.accept(...) checks for duplicate chunkSeq: tolerates byte-identical retransmissions, throws DuplicateChunkException for divergent duplicates of still-pending chunks. Test verifies both behaviors.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Poem

🐰 Across the network drops and bounces we hop,
Parked in patience till transport returns from the stop.
Fingerprints guard against duplicate claims,
While credentials dance through unknown schemes' games.
Budgets align in delegated grace,
And leases find their proper place.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/audit-issues-2026-06-11

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️