mirror of
https://github.com/PR0M3TH3AN/TORCH.git
synced 2026-10-27 07:51:52 +00:00
google-labs-jules[bot]andPR0M3TH3AN
aff47a7ba6
- Documented `src/lock-ops.mjs` in `docs/src-lock-ops-overview.md`. - Created required scheduler artifacts (`src/context/`, `src/todo/`, etc.). - Completed scheduler cycle and updated `task-logs/daily/`. - Updated `package-lock.json` with dependencies. Co-authored-by: PR0M3TH3AN <[email protected]>
51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# `src/lock-ops.mjs` Overview
|
|
|
|
This module implements the core logic for distributed locking using Nostr relays. It handles querying for existing locks, publishing new lock events, and managing relay health and fallbacks.
|
|
|
|
## High-Level Summary
|
|
The `lock-ops` module provides the mechanism for agents to coordinate and avoid race conditions. It uses ephemeral Nostr events (Kind `30078` parameterized replaceable events, though currently using `app_data`) to represent locks. It includes robust retry logic, relay health scoring, and fallback mechanisms to ensure reliability even when some relays are slow or offline.
|
|
|
|
## Public Surface
|
|
|
|
### `queryLocks(relays, cadence, dateStr, namespace, deps)`
|
|
Queries the specified relays for active locks matching the cadence and date.
|
|
- **relays**: Array of relay URLs.
|
|
- **cadence**: 'daily' or 'weekly'.
|
|
- **dateStr**: Date string (YYYY-MM-DD).
|
|
- **namespace**: Application namespace (e.g., 'torch').
|
|
- **Returns**: Array of active lock objects.
|
|
|
|
### `publishLock(relays, event, deps)`
|
|
Publishes a lock event to the specified relays, ensuring a quorum is met.
|
|
- **relays**: Array of relay URLs.
|
|
- **event**: The Nostr event object to publish.
|
|
- **Returns**: The published event if successful, throws error otherwise.
|
|
|
|
### `parseLockEvent(event)`
|
|
Parses a raw Nostr event into a structured lock object.
|
|
- **event**: Raw Nostr event.
|
|
- **Returns**: Structured lock object with `agent`, `cadence`, `expiresAt`, etc.
|
|
|
|
## Key Flows
|
|
|
|
1. **Lock Acquisition**:
|
|
- `queryLocks` is called to check for existing locks.
|
|
- If no valid lock exists, a new lock event is created (external to this module).
|
|
- `publishLock` is called to broadcast the event.
|
|
- Race check (reading back) confirms ownership (handled by caller, `src/lib.mjs`).
|
|
|
|
2. **Relay Health & Fallback**:
|
|
- Relays are scored based on latency and success rate.
|
|
- Failed attempts penalize the relay score.
|
|
- If primary relays fail, fallback relays are used.
|
|
|
|
## Invariants
|
|
- Locks must have an expiration time.
|
|
- A lock is only valid if it is the latest event for the `d` tag.
|
|
- Publishing requires a minimum number of successful relays (quorum).
|
|
|
|
## When to Change
|
|
- If the relay selection or scoring algorithm needs tuning.
|
|
- If the underlying Nostr event structure changes.
|
|
- If new telemetry or logging requirements arise.
|