@aiwg/cli 2026.7.21 → 2026.7.24

package/dist/src/sessions/repository.js

@@ -1,7 +1,10 @@
 import { createRequire } from 'node:module';
 import { CandidateReviewReceiptSchema, DeletionReceiptSchema, IntelligenceCandidateSchema, PromotionDependencyDecisionSchema, PromotionReceiptSchema, SessionContractError, sha256, } from './contracts.js';
+import { coverageFromBatchRun, } from './batch-contracts.js';
 import { redactSessionText, sanitizeNativeExtensions } from './policy.js';
 const require = createRequire(import.meta.url);
+const POLICY_PROVIDER_MIGRATION = 'policy-provider-identity:v2';
+const EVENT_ORIGIN_INTENT_MIGRATION = 'event-origin-intent:v1';
 export class SessionRepository {
     db;
     constructor(path = ':memory:') {
@@ -14,6 +17,7 @@ export class SessionRepository {
         }
         this.db.pragma('foreign_keys = ON');
         this.db.pragma('journal_mode = WAL');
+        this.db.pragma('busy_timeout = 5000');
         this.initialize();
     }
     initialize() {
@@ -24,6 +28,7 @@ export class SessionRepository {
       CREATE TABLE IF NOT EXISTS import_runs (
         import_run_id TEXT PRIMARY KEY, source_id TEXT NOT NULL, parser_version TEXT NOT NULL,
         status TEXT NOT NULL, checkpoint TEXT NOT NULL, data TEXT NOT NULL,
+        batch_run_id TEXT,
         FOREIGN KEY(source_id) REFERENCES session_sources(source_id)
       );
       CREATE TABLE IF NOT EXISTS sessions (
@@ -45,6 +50,12 @@ export class SessionRepository {
         outcome TEXT NOT NULL, counts TEXT NOT NULL, checkpoint TEXT NOT NULL,
         FOREIGN KEY(import_run_id) REFERENCES import_runs(import_run_id)
       );
+      CREATE TABLE IF NOT EXISTS batch_import_runs (
+        batch_run_id TEXT PRIMARY KEY, manifest_id TEXT NOT NULL,
+        workspace_id TEXT NOT NULL, status TEXT NOT NULL,
+        started_at TEXT NOT NULL, updated_at TEXT NOT NULL, data TEXT NOT NULL,
+        UNIQUE(manifest_id, workspace_id)
+      );
       CREATE TABLE IF NOT EXISTS mutation_audit (
         operation_id TEXT PRIMARY KEY, operation TEXT NOT NULL, actor TEXT NOT NULL,
         counts TEXT NOT NULL, adapter_version TEXT NOT NULL, policy_version TEXT NOT NULL,
@@ -89,6 +100,9 @@ export class SessionRepository {
         dependent_id TEXT NOT NULL, action TEXT NOT NULL, data TEXT NOT NULL,
         UNIQUE(operation_id, dependent_id)
       );
+      CREATE TABLE IF NOT EXISTS session_catalog_meta (
+        key TEXT PRIMARY KEY, value TEXT NOT NULL
+      );
       CREATE INDEX IF NOT EXISTS idx_session_workspace_provider
         ON sessions(workspace_id, source_id, lifecycle);
       CREATE INDEX IF NOT EXISTS idx_event_session_sequence
@@ -111,12 +125,20 @@ export class SessionRepository {
         if (!mutationColumns.includes('data')) {
             this.db.exec('ALTER TABLE mutation_audit ADD COLUMN data TEXT');
         }
+        const importRunColumns = this.db.prepare('PRAGMA table_info(import_runs)').all().map((row) => String(row.name));
+        if (!importRunColumns.includes('batch_run_id')) {
+            this.db.exec('ALTER TABLE import_runs ADD COLUMN batch_run_id TEXT');
+        }
         this.db.exec(`
       CREATE INDEX IF NOT EXISTS idx_mutation_audit_workspace
       ON mutation_audit(workspace_id, occurred_at, operation_id)
+      ;
+      CREATE INDEX IF NOT EXISTS idx_batch_import_workspace
+      ON batch_import_runs(workspace_id, updated_at, batch_run_id)
     `);
         this.alignSessionFtsRowids();
         this.migrateSessionPolicyAndProviderIdentity();
+        this.migrateEventOriginAndIntent();
     }
     alignSessionFtsRowids() {
         const eventCount = Number(this.db.prepare('SELECT COUNT(*) AS count FROM session_events').get()?.count ?? 0);
@@ -138,7 +160,7 @@ export class SessionRepository {
         rebuild();
     }
     migrateSessionPolicyAndProviderIdentity() {
-        const migrate = this.db.transaction(() => {
+        this.runCatalogMigration(POLICY_PROVIDER_MIGRATION, () => {
             for (const row of this.db.prepare('SELECT source_id, provider, data FROM session_sources').all()) {
                 const source = JSON.parse(String(row.data));
                 const canonicalProvider = source.provider === 'windsurf'
@@ -153,7 +175,7 @@ export class SessionRepository {
                 const session = JSON.parse(String(row.data));
                 if (session.provider === 'windsurf')
                     session.provider = 'devin-desktop';
-                session.extensions = sanitizeNativeExtensions(renameNativeWindsurfEnvelope(session.extensions)).value;
+                session.extensions = sanitizeSessionExtensions(renameNativeWindsurfEnvelope(session.extensions), session.provider);
                 this.db.prepare('UPDATE sessions SET data=? WHERE session_id=?')
                     .run(JSON.stringify(session), String(row.session_id));
             }
@@ -223,7 +245,52 @@ export class SessionRepository {
            WHERE operation_id=?`).run(workspaceId, event.targetClass, JSON.stringify(event), event.operationId);
             }
         });
-        migrate();
+    }
+    migrateEventOriginAndIntent() {
+        this.runCatalogMigration(EVENT_ORIGIN_INTENT_MIGRATION, () => {
+            for (const row of this.db.prepare('SELECT event_id, data FROM session_events').all()) {
+                const event = JSON.parse(String(row.data));
+                let changed = false;
+                if (typeof event.origin !== 'string') {
+                    event.origin = 'unknown';
+                    event.originRule = 'legacy:unknown';
+                    event.originClassifierVersion = '1.0.0';
+                    changed = true;
+                }
+                if (!Object.hasOwn(event, 'activityBoundary')) {
+                    event.activityBoundary = null;
+                    event.activityBoundaryBasis = null;
+                    event.activityBoundaryConfidence = null;
+                    changed = true;
+                }
+                if (changed) {
+                    this.db.prepare('UPDATE session_events SET data=? WHERE event_id=?').run(JSON.stringify(event), String(row.event_id));
+                }
+            }
+            for (const row of this.db.prepare('SELECT session_id, data FROM sessions').all()) {
+                const session = JSON.parse(String(row.data));
+                if (session.intent !== undefined)
+                    continue;
+                session.intent = {
+                    status: 'unknown',
+                    eventId: null,
+                    sequence: null,
+                    title: null,
+                    summary: null,
+                };
+                this.db.prepare('UPDATE sessions SET data=? WHERE session_id=?').run(JSON.stringify(session), String(row.session_id));
+            }
+        });
+    }
+    runCatalogMigration(migration, migrate) {
+        const applied = this.db.prepare('SELECT 1 AS applied FROM session_catalog_meta WHERE key=?').get(migration);
+        if (applied)
+            return;
+        const transaction = this.db.transaction(() => {
+            migrate();
+            this.db.prepare('INSERT INTO session_catalog_meta (key, value) VALUES (?, ?)').run(migration, 'applied');
+        });
+        transaction();
     }
     emitMutation(input) {
         const unsigned = {
@@ -344,8 +411,9 @@ export class SessionRepository {
             }
             this.db.prepare(`INSERT INTO session_sources(source_id, provider, data) VALUES (?, ?, ?)
          ON CONFLICT(source_id) DO UPDATE SET data=excluded.data`).run(batch.source.sourceId, batch.source.provider, JSON.stringify(batch.source));
-            this.db.prepare(`INSERT INTO import_runs(import_run_id, source_id, parser_version, status, checkpoint, data)
-         VALUES (?, ?, ?, 'running', ?, ?)`).run(batch.run.importRunId, batch.source.sourceId, batch.run.parserVersion, JSON.stringify(checkpoint), JSON.stringify(batch.run));
+            this.db.prepare(`INSERT INTO import_runs(
+           import_run_id, source_id, parser_version, status, checkpoint, data, batch_run_id
+         ) VALUES (?, ?, ?, 'running', ?, ?, ?)`).run(batch.run.importRunId, batch.source.sourceId, batch.run.parserVersion, JSON.stringify(checkpoint), JSON.stringify(batch.run), batch.batchRunId ?? null);
             let sessionsInserted = 0;
             let eventsInserted = 0;
             for (const session of batch.sessions) {
@@ -372,7 +440,25 @@ export class SessionRepository {
                 const prior = this.db.prepare('SELECT digest FROM session_events WHERE event_id=?')
                     .get(event.eventId);
                 if (prior && String(prior.digest) !== event.digest) {
-                    throw new SessionContractError('IMPORT_CONFLICT', `stable event identity changed content: ${event.eventId}`);
+                    const priorEvent = this.db.prepare(`SELECT e.data AS event_data, src.provider AS provider, s.native_session_id AS native_session_id
+             FROM session_events e
+             JOIN sessions s ON s.session_id=e.session_id
+             JOIN session_sources src ON src.source_id=e.source_id
+             WHERE e.event_id=?`).get(event.eventId);
+                    const priorCoordinates = priorEvent
+                        ? safeEventCoordinates(String(priorEvent.event_data), {
+                            provider: String(priorEvent.provider),
+                            nativeSessionId: String(priorEvent.native_session_id),
+                        })
+                        : { provider: '<unknown>', sourceId: '<unknown>', nativeSessionId: '<unknown>', nativeEventId: event.eventId };
+                    const incomingCoordinates = {
+                        provider: batch.source.provider,
+                        sourceId: event.sourceId,
+                        nativeSessionId: batch.sessions.find((session) => session.sessionId === event.sessionId)
+                            ?.nativeSessionId ?? event.sessionId,
+                        nativeEventId: event.nativeId ?? `sequence:${event.sequence}`,
+                    };
+                    throw new SessionContractError('IMPORT_CONFLICT', `stable event identity changed content: ${event.eventId}; prior=${formatEventCoordinates(priorCoordinates)} incoming=${formatEventCoordinates(incomingCoordinates)}`);
                 }
                 const inserted = insertEvent.run(event.eventId, event.sessionId, event.sourceId, event.importRunId, event.sequence, event.digest, JSON.stringify(event)).changes;
                 eventsInserted += inserted;
@@ -443,6 +529,53 @@ export class SessionRepository {
         });
         return commit();
     }
+    commitStagedBatch(batchRunId, sourceIds) {
+        if (sourceIds.length === 0)
+            return 0;
+        const placeholders = sourceIds.map(() => '?').join(', ');
+        const commit = this.db.transaction(() => {
+            const params = [batchRunId, ...sourceIds];
+            const staged = this.db.prepare(`SELECT import_run_id FROM import_runs
+         WHERE batch_run_id=? AND source_id IN (${placeholders}) AND status='staged'`).all(...params).map((row) => String(row.import_run_id));
+            const result = this.db.prepare(`UPDATE import_runs SET status='committed'
+         WHERE batch_run_id=? AND source_id IN (${placeholders}) AND status='staged'`).run(...params);
+            if (staged.length > 0) {
+                const runPlaceholders = staged.map(() => '?').join(', ');
+                this.db.prepare(`UPDATE import_receipts SET outcome='committed'
+           WHERE import_run_id IN (${runPlaceholders}) AND outcome='staged'`).run(...staged);
+            }
+            for (const operationId of staged) {
+                const row = this.db.prepare('SELECT data FROM mutation_audit WHERE operation_id=?').get(operationId);
+                if (!row?.data)
+                    continue;
+                const prior = JSON.parse(String(row.data));
+                const { integrityDigest: _integrityDigest, ...unsigned } = {
+                    ...prior,
+                    outcome: 'committed',
+                    observedAt: new Date().toISOString(),
+                };
+                const updated = {
+                    ...unsigned,
+                    integrityDigest: sha256(JSON.stringify(unsigned)),
+                };
+                this.db.prepare(`UPDATE mutation_audit SET outcome='committed', occurred_at=?, data=?
+           WHERE operation_id=?`).run(updated.observedAt, JSON.stringify(updated), operationId);
+            }
+            return result.changes;
+        });
+        return commit();
+    }
+    sourceImportTotals(sourceId, batchRunId) {
+        const events = Number(this.db.prepare(`SELECT COUNT(*) AS count
+       FROM session_events e
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       WHERE e.source_id=? AND r.batch_run_id=?`).get(sourceId, batchRunId)?.count ?? 0);
+        const sessions = Number(this.db.prepare(`SELECT COUNT(DISTINCT e.session_id) AS count
+       FROM session_events e
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       WHERE e.source_id=? AND r.batch_run_id=?`).get(sourceId, batchRunId)?.count ?? 0);
+        return { sessions, events };
+    }
     getSession(id, workspaceId) {
         const row = this.db.prepare(`SELECT s.data FROM sessions s
        WHERE s.session_id=? AND s.lifecycle != ?
@@ -458,6 +591,42 @@ export class SessionRepository {
     listSources() {
         return this.db.prepare('SELECT data FROM session_sources ORDER BY provider, source_id').all().map((row) => JSON.parse(String(row.data)));
     }
+    listWorkspaceIds() {
+        return this.db.prepare('SELECT DISTINCT workspace_id FROM sessions ORDER BY workspace_id').all().map((row) => String(row.workspace_id));
+    }
+    saveBatchImportRun(run) {
+        const save = this.db.transaction(() => {
+            const prior = this.db.prepare('SELECT manifest_id, workspace_id FROM batch_import_runs WHERE batch_run_id=?').get(run.runId);
+            if (prior && (String(prior.manifest_id) !== run.manifestId
+                || String(prior.workspace_id) !== run.workspaceId)) {
+                throw new SessionContractError('IMPORT_CONFLICT', 'batch run identity changed manifest or workspace scope');
+            }
+            this.db.prepare(`INSERT INTO batch_import_runs(
+           batch_run_id, manifest_id, workspace_id, status, started_at, updated_at, data
+         ) VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(batch_run_id) DO UPDATE SET
+           status=excluded.status, updated_at=excluded.updated_at, data=excluded.data`).run(run.runId, run.manifestId, run.workspaceId, run.status, run.startedAt, run.updatedAt, JSON.stringify(run));
+        });
+        save();
+    }
+    getBatchImportRun(runId) {
+        const row = this.db.prepare('SELECT data FROM batch_import_runs WHERE batch_run_id=?').get(runId);
+        return row ? JSON.parse(String(row.data)) : null;
+    }
+    getBatchImportRunForManifest(manifestId, workspaceId) {
+        const row = this.db.prepare(`SELECT data FROM batch_import_runs
+       WHERE manifest_id=? AND workspace_id=?`).get(manifestId, workspaceId);
+        return row ? JSON.parse(String(row.data)) : null;
+    }
+    getCoverage(workspaceId, now = new Date()) {
+        const row = this.db.prepare(`SELECT data FROM batch_import_runs
+       WHERE workspace_id=?
+       ORDER BY updated_at DESC, batch_run_id DESC LIMIT 1`).get(workspaceId);
+        const coverage = coverageFromBatchRun(row ? JSON.parse(String(row.data)) : null, now);
+        return coverage.status === 'unknown'
+            ? { ...coverage, workspaceId }
+            : coverage;
+    }
     listSessions(options) {
         const where = [`s.lifecycle != 'tombstoned'`, `EXISTS (
       SELECT 1 FROM session_events e
@@ -554,6 +723,23 @@ export class SessionRepository {
        ORDER BY e.sequence_no, e.event_id`).all(...(workspaceId ? [sessionId, workspaceId] : [sessionId]))
             .map((row) => JSON.parse(String(row.data)));
     }
+    listTimelineInputs(workspaceId) {
+        return this.db.prepare(`SELECT s.data AS session_data, e.data AS event_data
+       FROM session_events e
+       JOIN sessions s ON s.session_id=e.session_id
+       JOIN import_runs r ON r.import_run_id=e.import_run_id
+       WHERE s.workspace_id=? AND s.lifecycle!='tombstoned' AND r.status='committed'
+       ORDER BY
+         CASE WHEN json_extract(e.data, '$.occurredAt') IS NULL THEN 1 ELSE 0 END,
+         json_extract(e.data, '$.occurredAt'),
+         json_extract(s.data, '$.provider'),
+         e.session_id,
+         e.sequence_no,
+         e.event_id`).all(workspaceId).map((row) => ({
+            session: JSON.parse(String(row.session_data)),
+            event: JSON.parse(String(row.event_data)),
+        }));
+    }
     search(options) {
         const query = options.query.trim();
         if (!query)
@@ -889,6 +1075,13 @@ export class SessionRepository {
        ORDER BY rowid DESC LIMIT 1`).get(sourceId, parserVersion);
         return row ? JSON.parse(String(row.checkpoint)) : null;
     }
+    getBatchCheckpoint(sourceId, parserVersion, batchRunId) {
+        const row = this.db.prepare(`SELECT checkpoint FROM import_runs
+       WHERE source_id=? AND parser_version=? AND batch_run_id=?
+         AND status IN ('staged', 'committed')
+       ORDER BY rowid DESC LIMIT 1`).get(sourceId, parserVersion, batchRunId);
+        return row ? JSON.parse(String(row.checkpoint)) : null;
+    }
     relocateSource(sourceId, redactedLocator, workspaceId) {
         const relocate = this.db.transaction(() => {
             const row = this.db.prepare(`SELECT src.data FROM session_sources src
@@ -1269,6 +1462,7 @@ function searchHit(row) {
     const citation = {
         provider: session.provider,
         sessionId: event.sessionId,
+        origin: event.origin,
         eventId: event.eventId,
         importRunId: event.importRunId,
         sourceId: event.sourceId,
@@ -1281,6 +1475,7 @@ function searchHit(row) {
         provider: session.provider,
         workspaceId: session.workspaceId,
         sessionId: event.sessionId,
+        origin: event.origin,
         eventId: event.eventId,
         importRunId: event.importRunId,
         sourceId: event.sourceId,
@@ -1417,6 +1612,20 @@ function authorizedDocumentScopeDigest(options) {
     return sha256(JSON.stringify(scope));
 }
 function appendMetadataFilters(where, params, options) {
+    const controlEvents = options.controlEvents ?? 'exclude';
+    const controlOrigins = [
+        'provider-bootstrap',
+        'workspace-instruction',
+        'tool-control',
+    ];
+    if (controlEvents === 'exclude') {
+        where.push(`COALESCE(json_extract(e.data, '$.origin'), 'unknown') NOT IN (${controlOrigins.map(() => '?').join(',')})`);
+        params.push(...controlOrigins);
+    }
+    else if (controlEvents === 'only') {
+        where.push(`COALESCE(json_extract(e.data, '$.origin'), 'unknown') IN (${controlOrigins.map(() => '?').join(',')})`);
+        params.push(...controlOrigins);
+    }
     if (options.sessionIds?.length) {
         where.push(`e.session_id IN (${options.sessionIds.map(() => '?').join(',')})`);
         params.push(...options.sessionIds);
@@ -1517,26 +1726,158 @@ function mergeSessionAggregate(prior, incoming) {
         'consistent-snapshot': 1,
         complete: 2,
     };
-    const lifecycleRank = {
-        active: 0,
-        complete: 1,
-        tombstoned: 2,
-    };
+    const lifecycle = mergeLifecycleAggregate(prior, incoming);
+    const nativeKey = `native.${prior.provider}`;
+    const priorNative = objectRecord(prior.extensions[nativeKey]);
+    const incomingNative = objectRecord(incoming.extensions[nativeKey]);
     return {
         ...prior,
         startedAt: timestamp(prior.startedAt, incoming.startedAt, 'min'),
         updatedAt: timestamp(prior.updatedAt, incoming.updatedAt, 'max'),
         consistency: consistencyRank[prior.consistency] >= consistencyRank[incoming.consistency]
             ? prior.consistency : incoming.consistency,
-        lifecycle: lifecycleRank[prior.lifecycle] >= lifecycleRank[incoming.lifecycle]
-            ? prior.lifecycle : incoming.lifecycle,
+        lifecycle: lifecycle.lifecycle,
+        intent: mergeSessionIntent(prior.intent, incoming.intent),
         sourceDigest: incoming.sourceDigest,
         extensions: {
             ...prior.extensions,
             ...incoming.extensions,
+            [nativeKey]: {
+                ...priorNative,
+                ...incomingNative,
+                lifecycleEvidence: lifecycle.evidence,
+            },
         },
     };
 }
+function mergeLifecycleAggregate(prior, incoming) {
+    const nativeKey = `native.${prior.provider}`;
+    const priorEvidence = objectRecord(objectRecord(prior.extensions[nativeKey]).lifecycleEvidence);
+    const incomingEvidence = objectRecord(objectRecord(incoming.extensions[nativeKey]).lifecycleEvidence);
+    if (prior.lifecycle === 'tombstoned') {
+        return { lifecycle: prior.lifecycle, evidence: priorEvidence };
+    }
+    const rank = {
+        'open-provisional-source': 1,
+        'inactivity-threshold': 1,
+        'complete-source': 2,
+        'provider-explicit-event': 3,
+    };
+    const priorRank = rank[String(priorEvidence.basis)] ?? 0;
+    const incomingRank = rank[String(incomingEvidence.basis)] ?? 0;
+    const incomingIsNewer = lifecycleEvidenceTimestamp(incomingEvidence)
+        > lifecycleEvidenceTimestamp(priorEvidence);
+    return incomingRank > priorRank || (incomingRank === priorRank && incomingIsNewer)
+        ? { lifecycle: incoming.lifecycle, evidence: incomingEvidence }
+        : { lifecycle: prior.lifecycle, evidence: priorEvidence };
+}
+function objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function sanitizeSessionExtensions(extensions, provider) {
+    const sanitized = sanitizeNativeExtensions(extensions).value;
+    const nativeKey = `native.${provider}`;
+    const evidence = safeLifecycleEvidence(objectRecord(objectRecord(extensions[nativeKey]).lifecycleEvidence));
+    if (!evidence)
+        return sanitized;
+    sanitized[nativeKey] = {
+        ...objectRecord(sanitized[nativeKey]),
+        lifecycleEvidence: evidence,
+    };
+    return sanitized;
+}
+function safeLifecycleEvidence(evidence) {
+    const bases = new Set([
+        'open-provisional-source',
+        'inactivity-threshold',
+        'complete-source',
+        'provider-explicit-event',
+    ]);
+    const states = new Set([
+        'active', 'inactive', 'paused', 'complete', 'interrupted', 'archived',
+        'unknown', 'tombstoned',
+    ]);
+    const confidences = new Set(['high', 'medium', 'low', 'provisional']);
+    const basis = String(evidence.basis ?? '');
+    const state = String(evidence.state ?? '');
+    const confidence = String(evidence.confidence ?? '');
+    const observedAt = String(evidence.observedAt ?? '');
+    if (!bases.has(basis)
+        || !states.has(state)
+        || !confidences.has(confidence)
+        || !Number.isFinite(Date.parse(observedAt))) {
+        return null;
+    }
+    const output = {
+        basis,
+        state,
+        observedAt,
+        confidence,
+    };
+    if (typeof evidence.thresholdMs === 'number'
+        && Number.isFinite(evidence.thresholdMs)
+        && evidence.thresholdMs >= 0) {
+        output.thresholdMs = evidence.thresholdMs;
+    }
+    return output;
+}
+function lifecycleEvidenceTimestamp(value) {
+    const parsed = Date.parse(String(value.observedAt ?? ''));
+    return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
+}
+function mergeSessionIntent(prior, incoming) {
+    if (prior.status === 'selected' && incoming.status === 'selected') {
+        const priorKey = [prior.sequence ?? Number.MAX_SAFE_INTEGER, prior.eventId ?? ''];
+        const incomingKey = [incoming.sequence ?? Number.MAX_SAFE_INTEGER, incoming.eventId ?? ''];
+        return priorKey[0] < incomingKey[0]
+            || (priorKey[0] === incomingKey[0] && String(priorKey[1]) <= String(incomingKey[1]))
+            ? prior
+            : incoming;
+    }
+    if (prior.status === 'selected')
+        return prior;
+    if (incoming.status === 'selected')
+        return incoming;
+    if (prior.status === 'unknown' || incoming.status === 'unknown') {
+        return {
+            status: 'unknown',
+            eventId: null,
+            sequence: null,
+            title: null,
+            summary: null,
+        };
+    }
+    return prior;
+}
+function safeEventCoordinates(eventData, fallback) {
+    try {
+        const event = JSON.parse(eventData);
+        return {
+            provider: fallback.provider,
+            sourceId: event.sourceId,
+            nativeSessionId: fallback.nativeSessionId,
+            nativeEventId: event.nativeId ?? `sequence:${event.sequence}`,
+        };
+    }
+    catch {
+        return {
+            provider: fallback.provider,
+            sourceId: '<unreadable>',
+            nativeSessionId: fallback.nativeSessionId,
+            nativeEventId: '<unreadable>',
+        };
+    }
+}
+function formatEventCoordinates(input) {
+    return [
+        `provider=${input.provider}`,
+        `source=${input.sourceId}`,
+        `session=${input.nativeSessionId}`,
+        `event=${input.nativeEventId}`,
+    ].join(',');
+}
 function allowedCandidateTransition(from, to) {
     const transitions = {
         pending: new Set(['accepted', 'rejected', 'deferred']),

package/dist/src/sessions/timeline.js

@@ -0,0 +1,148 @@
+export const TIMELINE_SCHEMA_VERSION = '1.0.0';
+export const DEFAULT_TIMELINE_GAP_MS = 30 * 60 * 1_000;
+export function deriveSessionTimeline(input, gapMs = DEFAULT_TIMELINE_GAP_MS) {
+    if (!Number.isFinite(gapMs) || gapMs < 0) {
+        throw new Error('timeline gap must be a non-negative duration');
+    }
+    const grouped = new Map();
+    for (const item of input) {
+        const group = grouped.get(item.session.sessionId) ?? [];
+        group.push(item);
+        grouped.set(item.session.sessionId, group);
+    }
+    const result = [];
+    for (const items of grouped.values()) {
+        const timed = items
+            .filter((item) => item.event.occurredAt !== null)
+            .sort(compareTimelineInput);
+        const untimed = items
+            .filter((item) => item.event.occurredAt === null)
+            .sort(compareSequence);
+        if (timed.length === 0) {
+            const first = items[0];
+            result.push({
+                schemaVersion: TIMELINE_SCHEMA_VERSION,
+                provider: first.session.provider,
+                sessionId: first.session.sessionId,
+                segmentIndex: 0,
+                startAt: null,
+                endAt: null,
+                durationMs: null,
+                eventCount: untimed.length,
+                boundaryBasis: 'unknown-time',
+                boundaryEvidence: null,
+                confidence: 'low',
+                minSequence: untimed.at(0)?.event.sequence ?? 0,
+                maxSequence: untimed.at(-1)?.event.sequence ?? 0,
+            });
+            continue;
+        }
+        const sessionSegments = [];
+        let current = null;
+        let previous = null;
+        for (const item of timed) {
+            const boundary = previous ? segmentBoundary(previous.event, item.event, gapMs) : null;
+            if (!current || boundary) {
+                current = {
+                    schemaVersion: TIMELINE_SCHEMA_VERSION,
+                    provider: item.session.provider,
+                    sessionId: item.session.sessionId,
+                    segmentIndex: sessionSegments.length,
+                    startAt: item.event.occurredAt,
+                    endAt: item.event.occurredAt,
+                    durationMs: 0,
+                    eventCount: 0,
+                    boundaryBasis: boundary?.basis ?? 'session-start',
+                    boundaryEvidence: boundary?.evidence ?? null,
+                    confidence: boundary?.confidence ?? 'high',
+                    minSequence: item.event.sequence,
+                    maxSequence: item.event.sequence,
+                };
+                sessionSegments.push(current);
+            }
+            current.eventCount += 1;
+            current.endAt = item.event.occurredAt;
+            current.durationMs = Math.max(0, Date.parse(current.endAt) - Date.parse(current.startAt));
+            current.minSequence = Math.min(current.minSequence, item.event.sequence);
+            current.maxSequence = Math.max(current.maxSequence, item.event.sequence);
+            previous = item;
+        }
+        for (const item of untimed) {
+            const destination = sessionSegments.find((segment) => item.event.sequence <= segment.maxSequence) ?? sessionSegments.at(-1);
+            destination.eventCount += 1;
+            destination.minSequence = Math.min(destination.minSequence, item.event.sequence);
+            destination.maxSequence = Math.max(destination.maxSequence, item.event.sequence);
+        }
+        result.push(...sessionSegments);
+    }
+    return result
+        .sort((left, right) => compareNullableTime(left.startAt, right.startAt)
+        || left.provider.localeCompare(right.provider)
+        || left.sessionId.localeCompare(right.sessionId)
+        || left.segmentIndex - right.segmentIndex)
+        .map(({ minSequence: _min, maxSequence: _max, ...segment }) => segment);
+}
+export function parseTimelineGap(value) {
+    if (value === undefined)
+        return DEFAULT_TIMELINE_GAP_MS;
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value.trim());
+    if (!match)
+        throw new Error('timeline gap must use ms, s, m, h, or d (for example 30m)');
+    const factors = {
+        ms: 1,
+        s: 1_000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    const result = Number(match[1]) * factors[match[2]];
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new Error('timeline gap is outside the supported duration range');
+    }
+    return result;
+}
+function segmentBoundary(previous, current, gapMs) {
+    if (current.activityBoundary === 'resume'
+        || current.activityBoundary === 'continuation') {
+        return {
+            basis: 'provider-explicit',
+            evidence: current.activityBoundaryBasis ?? current.activityBoundary,
+            confidence: current.activityBoundaryConfidence ?? 'high',
+        };
+    }
+    if (previous.activityBoundary === 'pause' || previous.activityBoundary === 'end') {
+        return {
+            basis: 'provider-explicit',
+            evidence: previous.activityBoundaryBasis ?? previous.activityBoundary,
+            confidence: previous.activityBoundaryConfidence ?? 'high',
+        };
+    }
+    const gap = Date.parse(current.occurredAt) - Date.parse(previous.occurredAt);
+    if (gap > gapMs) {
+        return {
+            basis: 'inferred-gap',
+            evidence: `inactivity>${gapMs}ms`,
+            confidence: 'medium',
+        };
+    }
+    return null;
+}
+function compareTimelineInput(left, right) {
+    return Date.parse(left.event.occurredAt) - Date.parse(right.event.occurredAt)
+        || left.event.sequence - right.event.sequence
+        || left.event.eventId.localeCompare(right.event.eventId);
+}
+function compareSequence(left, right) {
+    return left.event.sequence - right.event.sequence
+        || left.event.eventId.localeCompare(right.event.eventId);
+}
+function compareNullableTime(left, right) {
+    if (left === right)
+        return 0;
+    if (left === null)
+        return 1;
+    if (right === null)
+        return -1;
+    return Date.parse(left) - Date.parse(right);
+}
+//# sourceMappingURL=timeline.js.map