A stateless, deterministic sync worker implementing the Declarative Reconciliation Loop (DRL) pattern to bidirectionally sync Google Calendar events and Linear issues.

This refactored implementation follows a strict Observe → Project → Diff → Actuate pattern:

1. Observe: Fetch current snapshots from Linear and Google Calendar APIs
2. Project: Create a canonical truth using deterministic, side-effect-free functions
3. Diff: Compare canonical state with external reality to compute minimal operations
4. Actuate: Execute idempotent API calls until external systems match canonical truth

• Stateless: No database required; all state lives in remote systems via UID linkages
• Deterministic: Pure functions ensure identical inputs always produce identical outputs
• Idempotent: Operations can be safely retried without side effects
• Minimal: Only necessary changes are made to external systems

interface GCalEvent {
  id: string; // Primary key (never edited)
  summary: string; // Prefix + human title
  description?: string; // Freeform notes
  start: { dateTime: string }; // ISO 8601 UTC
  end: { dateTime: string }; // ISO 8601 UTC
  extendedProperties?: {
    private?: {
      uid?: string; // Canonical UID linking to Linear
      linearIssueId?: string; // Back-pointer to Linear issue
    };
  };
  status: "confirmed" | "cancelled";
}

interface LinearIssue {
  id: string; // Primary key
  title: string; // Prefix + human title
  description?: string; // Long notes + calendar metadata
  state: "Triage" | "Scheduled" | "Done" | "Canceled" | "Failed";
  targetDate?: string; // ISO 8601 datetime
  // Note: Linear API doesn't support custom fields - use description metadata instead
}

The unified representation that bridges both systems:

interface CanonicalItem {
  uid: string; // Stable identifier across systems
  title: string; // Clean title (no prefix)
  description?: string;
  startTime?: string; // ISO 8601
  endTime?: string; // ISO 8601
  linearId?: string;
  gcalId?: string;
  linearState?: LinearIssue["state"];
  phase: Phase; // Current lifecycle phase
  lastModified: string; // For conflict resolution
}

The system recognizes 5 phases with specific transition rules:

• 📥 Triage: New items from Google Calendar awaiting review
• 📅 Scheduled: Items scheduled for specific times
• ✅ Done: Completed items
• 🚫 Canceled: Canceled items
• ❌ Failed: Failed items
• ⏳ Worked: Original events that went overdue (shows work was done)

| active → active | Title/time/description change | Sync metadata | (unchanged) |

The system uses two linking mechanisms:

1. GCal → Linear: extendedProperties.private.linearIssueId in calendar events
2. Linear → GCal: Description metadata <!-- calendar-sync --> GoogleCalEventId:xyz in Linear issues

This approach works because:

• Google Calendar API supports extendedProperties for metadata storage
• Linear API doesn't support custom fields, so we embed metadata in descriptions
• Both systems preserve their metadata across updates

• Title: Linear wins (source of truth for task names)
• Start/End Times: Calendar wins (source of truth for scheduling)
• Description: Newest updatedAt wins (simplified to Linear in current implementation)

src/
├── types.ts          # Core data models and interfaces
├── projector.ts      # Observe → Project (create canonical truth)
├── diff.ts           # Project → Diff (compute operations)
├── actuator.ts       # Diff → Actuate (execute operations)
├── worker.ts         # Main sync orchestrator
├── main.ts           # Entry point with configuration
└── *.test.ts         # Comprehensive test suite

deno test --allow-env --allow-net --allow-import src/*.test.ts

# Set environment variables
export LINEAR_API_KEY="your-linear-api-key"
export LINEAR_TEAM_ID="your-team-id"
export GCAL_API_KEY="your-google-api-key"
export GCAL_CALENDAR_ID="your-calendar-id"

# Run sync
deno run --allow-env --allow-net src/main.ts

The worker is configured via environment variables:

• LINEAR_API_KEY: Linear API token
• LINEAR_TEAM_ID: Linear team identifier
• GCAL_API_KEY: Google Calendar API key
• GCAL_CALENDAR_ID: Primary calendar ID
• GCAL_HISTORY_CALENDAR_ID: (Optional) Calendar for overdue items
• TIMEZONE: Timezone for operations (default: UTC)
• LOOKBACK_DAYS: Days to look back (default: 30)
• LOOKAHEAD_DAYS: Days to look ahead (default: 90)

• Latency: < 5 seconds for 10,000 items (per spec requirement)
• Memory: Stateless operation, minimal memory footprint
• Network: Batched API calls, efficient pagination
• Reliability: Idempotent operations survive failures

The test suite covers:

• Unit tests: Individual functions (types, projector, diff)
• Integration tests: Full sync workflows with mock APIs
• Determinism: Identical inputs produce identical outputs
• Idempotence: Operations can be safely retried
• Performance: Validates < 5s execution time

The DRL pattern makes it easy to:

1. Add new external systems (e.g., Notion) by implementing new projectors/actuators
2. Add new phase transitions by updating the diff engine
3. Add new conflict resolution rules in the projector
4. Add webhook triggers by replacing the cron scheduler

The original implementation has been moved to backup/ and key concepts have been preserved:

• Bidirectional sync logic
• State machine approach (now phase-based)
• Metadata embedding for linkage
• Prefix-based visual indicators

The new implementation is more robust, testable, and maintainable while preserving all original functionality.