#Chronos Human Activity Observability & Time Tracking (@xtnd/vantage-chronos)

Package: @xtnd/vantage-chronos
Source Directory: xtnd-vantage/packages/chronos/

#1. Overview

@xtnd/vantage-chronos provides the human activity telemetry, retrospective evidence collection, multi-signal attribution, work session coalescing, and Notion timesheet reconciliation module for the XTND Vantage platform.

Complementing Sonar (AI telemetry & token accounting) and Radar (web UX telemetry), Chronos provides observation and attribution for work performed by humans across diverse communication and desktop environments.

#2. The 5-Stage Retrospective Pipeline

flowchart TD
    subgraph Sources["1. Multi-Source Evidence Ingestion"]
        E["Apple Mail (.emlx / SQLite)"]
        W["WhatsApp (Messages & Calls)"]
        P["macOS Phone Call History"]
        G["Git Commits & Reflog"]
        A["Computer / App Window Activity"]
        N["Notion Existing Tasks & Entries"]
    end

    subgraph Collect["2. Normalization & Collection"]
        Col["ChronosEvidenceCollector"]
    end

    subgraph Attr["3. Contextual Attribution (Kairos Engine)"]
        Eng["ContextualAttributionEngine\n(Multi-Signal Scoring: Keywords, IDs, Proximity)"]
    end

    subgraph Sess["4. Work Session Coalescing & Duration"]
        Coalesce["WorkSessionCoalescer\n(Gap Clustering, Deduping)"]
        Dur["DurationEstimator\n(Independent Duration Confidence, 15m Rounding)"]
    end

    subgraph Reconcile["5. Notion Reconciliation"]
        Rec["ReconciliationEngine\n(Overlap Prevention, Duplicate Filtering)"]
        Sync["NotionSyncBridge\n(Database Formatter)"]
    end

    E & W & P & G & A & N --> Col
    Col --> Eng
    Eng --> Coalesce
    Coalesce --> Dur
    Dur --> Rec
    Rec --> Sync

#3. Core Capabilities

#3.1 Multi-Signal Contextual Attribution

Attribution is computed from multiple weighted signals rather than naive single-parameter matching:

• Explicit Project Name / Alias Match: 0.50 weight
• Technical Domain Identifiers (order numbers like ORD-9821, ticket keys, filenames): 0.45 weight
• Git Repository Association: 0.40 weight
• Distinctive Subject Keywords: up to 0.40 weight
• Contact Association Disambiguation: Evaluates whether a contact (e.g. Jørgen) works exclusively on one project or across multiple projects. If shared across projects, flags ambiguous matches unless reinforced by other identifiers or surrounding context.
• Temporal Proximity: Surrounding correspondence within ±25 minutes reinforces adjacent ambiguous records.

#3.2 Work Session Coalescing

• Groups clustered traces into coherent work blocks.
• Strips duplicate echoes (e.g. forwarded emails, quoted reply chains, repeated commit pushes).
• Splits sessions when idle gap exceeds threshold (default: 20 minutes).

#3.3 Independent Duration Determination

• Attribution confidence and duration confidence are tracked separately.
• Measured calls: Uses telephony / WhatsApp call durations, rounded up to the next 15-minute unit (duration confidence: 0.95).
• Active window bursts: Uses focused window time minus idle gaps (duration confidence: 0.85).
• Git bursts: Computes commit span plus standard preparation/test buffer (duration confidence: 0.75).
• Retrospective heuristics: Estimates email exchanges and review sessions (duration confidence: 0.65).

#3.4 Notion Timesheet Reconciliation

• Compares proposed work sessions with existing Notion entries.
• Detects time overlaps on the same day:
  • If project matches: skips duplicate entry (duplicate_skipped).
  • If project differs: flags conflict for human review (conflict_flagged).
  • If unrecorded: creates new draft with audit rationale (new).

#4. Usage Example

import { VantageChronos, MemoryStorageAdapter, VantageStorageManager } from '@xtnd/vantage';

const storage = new MemoryStorageAdapter();
const manager = new VantageStorageManager({ storageAdapter: storage, autoStartSync: false });

const chronos = new VantageChronos(manager, [
  {
    projectId: 'proj-planorama',
    projectName: 'Planorama',
    identifiers: ['ORD-9821'],
    keywords: ['webordre', 'registration'],
    knownContacts: ['jorgen@xtnd.io'],
  },
]);

// 1. Record evidence
chronos.collector.recordEmail({
  messageId: 'mail-100',
  timestamp: Date.now() - 3600000,
  sender: 'client@example.com',
  recipients: ['peter@xtnd.io'],
  subject: 'Webordre ORD-9821 fejl',
  bodyExcerpt: 'Kunden mangler registrering.',
});

// 2. Reconstruct sessions
const sessions = chronos.reconstructSessions();

// 3. Reconcile with Notion
const drafts = chronos.reconcileNotion([]);
console.log(drafts[0]);

#5. Exporters: XVantage Primary & Pluggable Adapters

As an official XTND Vantage product, Chronos exports first and foremost to the XVantage API and Server as the canonical system-of-record. Downstream adapters then optionally sync entries to third-party tools.

#5.1 Primary: Canonical XVantage Server Exporter (VantageServerExporter)

• Dispatches timesheets and work sessions directly to https://api.chronos.vantage.xgi.io/v1/timesheets/entries.
• Integrates human labor costs with Sonar AI token costs and Aegis incident records for unified project cost observability.

#5.2 Downstream Adapters

• Notion Exporter (NotionSyncBridge): Formats 4-block structured audit pages and synchronizes with the Notion Time Tracker database.
• Clockify Exporter (ClockifySyncBridge): Formats entries for Clockify workspaces, projects, tasks, and tags.
• Toggl Track Exporter (TogglSyncBridge): Formats entries for Toggl Track v9 API with project IDs and reference tags.
• Generic File Exporters: Generates machine-readable JSON audit logs or accounting CSVs.