Docs: Complete Heart API reference with missing methods

[kluth]

Problem

Heart API Reference section is incomplete, missing several important methods that are documented in usage examples.

Affected Files

Documentation: /home/matthias/projects/synapse/docs/systems/circulatory/README.md (lines 676-711)

Issue Details

Severity: HIGH
Impact: Developers consulting API reference won't find important methods

Missing from API Reference

The following methods are documented in usage sections but NOT in the formal API Reference:

1. onDeadLetter() - Documented in usage (lines 527-535) but not in API Reference
2. getStatistics() - Documented in usage (lines 541-546) but not in API Reference
3. getQueueSize() - Documented in usage (lines 548-554) but not in API Reference
4. onAcknowledge() - Documented in usage but not in API Reference

Missing Type Definitions

API Reference also lacks:

• HeartOptions interface definition
• PublishOptions interface definition
• HeartStatistics interface definition

Impact

Developers consulting the formal API reference will miss key methods and configuration options.

Required Additions

interface HeartOptions {
  persistence?: boolean;      // Enable message persistence (default: false)
  maxQueueSize?: number;      // Maximum queue capacity (default: 10000)
}

interface HeartStatistics {
  published: number;
  delivered: number;
  failed: number;
  deadLettered: number;
}

class Heart {
  constructor(options?: HeartOptions);
  
  // ... existing methods ...
  
  // Add these to API Reference:
  onDeadLetter(handler: (cell: BloodCell) => void): void;
  onAcknowledge(handler: (cell: BloodCell) => void): void;
  getStatistics(): HeartStatistics;
  getQueueSize(): number;
}

Priority

HIGH - API reference is critical documentation for developers

References

• Documentation Issue Log: /home/matthias/projects/synapse/DOCUMENTATION_ISSUE_LOG.md (Issues ci: Bump oven-sh/setup-bun from 1 to 2 #2, ci: Bump github/codeql-action from 3 to 4 #3)
• Documentation Fixes Needed: /home/matthias/projects/synapse/DOCUMENTATION_FIXES_NEEDED.md (FIX-4)

User Story

As a developer, I want a complete API reference for the Heart class, so that I can discover and use all available methods without searching through usage examples.

Acceptance Criteria

• Add all missing methods to API Reference section
• Document HeartOptions interface with defaults and descriptions
• Document HeartStatistics interface
• Document PublishOptions interface
• Include return types and parameters for all methods
• Add behavioral descriptions for each method

[kluth]

Fixed in commit aa6b17b. Updated Heart API reference documentation to match the actual implementation: changed getStatistics() to getStats() and added missing methods (getPersistedMessages, replay, stop). The documentation now accurately reflects all available Heart methods.