Interface ConsensusService

All Superinterfaces:
AutoCloseable
public interface ConsensusService extends AutoCloseable
Local Raft-like replicated log service for J7M platform metadata.

This API is a stable public service contract. Implementations own local durable term, vote, log, commit, and recovery state, and may block while appending to or replaying the local durable log. Implementations are expected to be thread-safe for concurrent callers unless they document a stricter ownership model. Returned status and safety reports are redacted summaries: they must not expose raw command payload bytes, credentials, private endpoint material, or implementation-only transport state.

The Phase 6.5 contract is intentionally scoped: it is not a general database, not a durable queue, not repository replication, not a transaction engine, and not generic exactly-once execution. Implementations map invalid input, unavailable leadership, stale terms, recovery failures, and durable storage failures to stable middleware error codes through the configured exception model.

API note: The baseline J7M implementation is in-process and deterministic for validation. Production deployments may wrap this service with transport or ownership layers, but the public API does not define a vendor protocol.

  • Method Details

    • startElection

      ConsensusState startElection(ConsensusNodeId nodeId)
      Starts an election from the supplied node in deterministic local simulation.

      The call may synchronously persist a new term and vote before returning. It must reject unknown nodes and stale terms consistently with the implementation's membership model. The returned state is a redacted snapshot and not a mutable node handle.

      Parameters:
      nodeId - candidate node; must identify a configured member
      Returns:
      elected leader state or current node state after the election attempt

    • submit

      ConsensusCommandResult submit(ConsensusCommand command)
      Submits a metadata command to the current leader.

      The command is replicated according to the majority commit rule before a committed result is reported. The method may block on local durable-log appends and deterministic message processing. Implementations must reject stale leaders and must redact command payloads from status, metrics, safety reports, and exception details.

      Parameters:
      command - metadata command to append; payload bytes remain internal
      Returns:
      command result with committed/rejected status and safe reason code

    • status

      ConsensusStatus status()
      Returns current safe status.

      The snapshot is intended for operators and tests. It exposes role, term, commit index, applied index, metrics, and redacted log-entry metadata; it does not expose raw ConsensusCommand payloads.

      Returns:
      immutable redacted status snapshot

    • safetyReport

      ConsensusSafetyReport safetyReport()
      Runs safety invariant checks.

      Implementations inspect actual recovered node state, logs, commit indexes, and recorded simulation evidence. Required invariants must fail or report insufficient evidence rather than silently passing when a scenario was not exercised.

      Returns:
      redacted safety report containing safe evidence and violations

    • close

      void close()
      Closes local resources.

      Implementations should make close idempotent. After close, mutating operations should fail with a stable unavailable/closed error rather than exposing implementation resource details.

      Specified by:
      close in interface AutoCloseable