graphlin 0.1.3 → 0.2.0

package/runtime/platform.mjs

@@ -0,0 +1,254 @@
+import path from 'node:path';
+import { createInventory, extractStructure } from './discovery/index.mjs';
+import { createProjectModel } from './model/index.mjs';
+import { integer, isHash, isId } from './core/common.mjs';
+import { relativePath, currentPolicy } from './model/records.mjs';
+
+const SOURCE = /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|rb|php|cs|swift|sql|ya?ml|json|toml|tf)$/i;
+const QUEUE_LIMIT = 32, TRACKED_LIMIT = 10000, FILE_BYTES = 256 * 1024;
+const version = artifact => `${artifact.hash}:${artifact.generation}`;
+const eligiblePath = value => SOURCE.test(value) && !/(?:package-lock|pnpm-lock|yarn\.lock)/.test(value);
+
+/** Coordinates bounded local exploration without coupling model facts to a view. */
+export function createPlatform({
+  projectRoot, projectId, policy = {}, restoredState, now = Date.now,
+  accept = operation => operation(), revalidate = async () => true, onChange = () => {},
+  extract = extractStructure,
+}) {
+  const model = createProjectModel({ projectId, policy, restoredState, now });
+  let inventory = createInventory({ projectRoot, excludePaths: currentPolicy(policy).excludePaths });
+  const parsed = new Map(), queue = new Map(), latest = new Map(), deferred = new Map(), undispatched = new Set();
+  const errors = { failed: 0, stale: 0, omitted: 0 };
+  let lineageId = model.snapshot().coverage.lineage?.id ?? null;
+  let lineageEpoch = 0;
+  let lastError = null;
+  let active = null, processing = null, closed = false, finishedScanAt = null;
+
+  function notify() {
+    try {
+      Promise.resolve(onChange()).catch(() => { lastError = 'observer_failed'; });
+    } catch { lastError = 'observer_failed'; }
+  }
+  function rememberDeferred(artifact, reason) {
+    if (!artifact.relativePath || !currentPolicy(policy).readSource) return;
+    if (!deferred.has(artifact.id) && deferred.size >= TRACKED_LIMIT) { errors.omitted++; return; }
+    // Deferred work retains names/versions only. Normal discovery/capture must
+    // reacquire authorized source; overflow never becomes a hidden source cache.
+    deferred.set(artifact.id, {
+      id: artifact.id, relativePath: artifact.relativePath, hash: artifact.hash,
+      generation: artifact.generation, reason,
+    });
+  }
+  function failure(reason, artifact) {
+    errors.failed++;
+    lastError = reason;
+    if (artifact && isCurrent(artifact)) rememberDeferred(artifact, reason);
+    model.recordActivity({ kind: reason, outcome: 'unresolved', artifactIds: artifact ? [artifact.id] : [] });
+    notify();
+  }
+  function isCurrent(artifact) {
+    const observed = latest.get(artifact.id), effective = currentPolicy(policy);
+    return !closed && effective.readSource && observed?.status === 'present' &&
+      artifact.lineageId === lineageId && artifact.lineageEpoch === lineageEpoch && version(observed) === version(artifact) &&
+      !!relativePath(artifact.relativePath, effective);
+  }
+
+  function pump() {
+    if (active || closed || !queue.size) return;
+    const [id, item] = queue.entries().next().value;
+    queue.delete(id);
+    const controller = new AbortController();
+    processing = { id, artifact: item.artifact, version: version(item.artifact), controller };
+    active = (async () => {
+      const { artifact, event } = item;
+      if (!isCurrent(artifact)) { errors.stale++; return; }
+      const structure = await extract({
+        artifactId: artifact.id, relativePath: artifact.relativePath, text: artifact.text,
+        hash: artifact.hash, generation: artifact.generation, complete: artifact.complete, signal: controller.signal,
+      });
+      if (!isCurrent(artifact)) { errors.stale++; return; }
+      let current;
+      try { current = await revalidate([{ artifactId: id, hash: artifact.hash, generation: artifact.generation }]); }
+      catch { failure('parse.revalidation_failed', artifact); return; }
+      if (!current || !isCurrent(artifact)) {
+        errors.stale++;
+        if (isCurrent(artifact)) rememberDeferred(artifact, 'revalidation_required');
+        return;
+      }
+      if (!structure?.enumeration || structure.enumeration.artifactId !== id ||
+          version(structure.enumeration) !== version(artifact)) {
+        failure('parse.invalid_result', artifact);
+        return;
+      }
+      try { await accept(() => {
+        // The worktree may advance between async revalidation and serialized
+        // acceptance. Recheck here before either admission or cache completion.
+        if (!isCurrent(artifact)) { errors.stale++; return; }
+        const before = model.stats();
+        const observation = model.observeStructure(structure, { event });
+        const after = model.stats();
+        if (!observation.accepted || after.deferred.entities > before.deferred.entities) {
+          rememberDeferred(artifact, 'model_capacity');
+          return;
+        }
+        if (structure.enumeration.omissions?.includes('parser_unavailable')) {
+          failure('parse.unavailable', artifact);
+          return;
+        }
+        parsed.set(id, version(artifact));
+        deferred.delete(id);
+        notify();
+      }); } catch { failure('parse.accept_failed', artifact); }
+    })().catch(() => {
+      if (isCurrent(item.artifact) && !controller.signal.aborted) failure('parse.failed', item.artifact);
+      else errors.stale++;
+    }).finally(() => { active = null; processing = null; pump(); });
+  }
+
+  function retryPaths() {
+    if (!currentPolicy(policy).readSource) return [];
+    return [...deferred.values()].slice(0, QUEUE_LIMIT).flatMap(item => {
+      const name = relativePath(item.relativePath, currentPolicy(policy));
+      return name ? [path.join(projectRoot, name)] : [];
+    });
+  }
+  function dispatch(limit) {
+    const pending = [...new Set([...retryPaths(), ...undispatched])].slice(0, limit);
+    for (const name of pending) undispatched.delete(name);
+    // Sort the selected bounded batch, not the filesystem traversal. Metadata
+    // displaced by retries remains pending for the next discovery slice.
+    return pending.sort();
+  }
+  function stats() {
+    return {
+      queued: queue.size, active: active ? 1 : 0, deferred: deferred.size + undispatched.size, parsed: parsed.size,
+      ...errors, lastError,
+    };
+  }
+  return {
+    model,
+    async discover({ limit = 64 } = {}) {
+      if (closed) return [];
+      const batchLimit = integer(limit, 1) ? Math.min(limit, 64) : 64;
+      try {
+        if (finishedScanAt !== null) {
+          if (now() - finishedScanAt < 5000) return dispatch(batchLimit);
+          await inventory.close();
+          inventory = createInventory({ projectRoot, excludePaths: currentPolicy(policy).excludePaths });
+          finishedScanAt = null;
+        }
+        const result = await inventory.next({ limit: batchLimit });
+        model.observeInventory(result);
+        if (!result.continuation) finishedScanAt = now();
+        for (const file of result.paths.filter(eligiblePath)) {
+          if (undispatched.size < TRACKED_LIMIT) undispatched.add(path.join(projectRoot, file));
+          else errors.omitted++;
+        }
+        return dispatch(batchLimit);
+      } catch {
+        failure('inventory.failed');
+        return dispatch(batchLimit);
+      }
+    },
+    observeArtifacts(artifacts, event) {
+      if (closed || !Array.isArray(artifacts)) return;
+      model.invalidateArtifacts(artifacts);
+      const overflow = [];
+      for (const input of artifacts.slice(0, TRACKED_LIMIT)) {
+        if (!isId(input?.id) || !integer(input.generation, 1)) continue;
+        const old = latest.get(input.id);
+        if (old && (input.generation < old.generation || input.generation === old.generation &&
+            (old.hash && input.hash && old.hash !== input.hash || old.status !== 'present' && input.status === 'present'))) {
+          errors.stale++;
+          continue;
+        }
+        if (!old && latest.size >= TRACKED_LIMIT) { errors.omitted++; continue; }
+        const effective = currentPolicy(policy);
+        const name = relativePath(input.relativePath, effective);
+        const artifact = { id: input.id, relativePath: name, hash: input.hash,
+          generation: input.generation, status: input.status, complete: input.complete === true, lineageId, lineageEpoch };
+        latest.set(input.id, artifact);
+        if (processing?.id === input.id && (processing.version !== version(artifact) || artifact.status !== 'present')) {
+          processing.controller.abort();
+        }
+        if (!effective.readSource || !name || !eligiblePath(name) || !isHash(input.hash) ||
+            typeof input.text !== 'string' || Buffer.byteLength(input.text) > FILE_BYTES || input.status !== 'present') {
+          queue.delete(input.id);
+          deferred.delete(input.id);
+          parsed.delete(input.id);
+          continue;
+        }
+        if (parsed.get(input.id) === version(artifact)) {
+          deferred.delete(input.id);
+          continue;
+        }
+        if (processing?.id === input.id && processing.version === version(artifact) &&
+            processing.artifact.lineageEpoch === lineageEpoch) continue;
+        if (!queue.has(input.id) && queue.size >= QUEUE_LIMIT) {
+          if (!deferred.has(input.id)) overflow.push(input.id);
+          rememberDeferred(artifact, 'queue_capacity');
+          continue;
+        }
+        const correlation = event ? { id: event.id, kind: event.kind, sessionId: event.sessionId } : undefined;
+        // A pre-tool event may accompany a real capture, but is not its source
+        // attribution. Only the separately captured, revalidated bytes are parsed.
+        queue.set(input.id, {
+          artifact: { ...artifact, text: input.text },
+          event: event?.kind === 'tool.requested' ? undefined : correlation,
+        });
+        deferred.delete(input.id);
+      }
+      if (overflow.length) model.recordActivity({ kind: 'parse.deferred', outcome: 'unresolved', artifactIds: overflow.slice(0, 256) });
+      pump();
+    },
+    observeLineage(value) {
+      const before = model.stats().revision;
+      const result = model.observeLineage(value);
+      const nextId = result.lineage?.id ?? null;
+      if (result.changed) {
+        lineageEpoch++;
+        parsed.clear();
+        queue.clear();
+        deferred.clear();
+        processing?.controller.abort();
+        for (const artifact of latest.values()) rememberDeferred(artifact, 'lineage_changed');
+      } else if (lineageId === null && nextId !== null) {
+        // Initial metadata names the current work; it is not a branch switch.
+        for (const item of queue.values()) item.artifact.lineageId = nextId;
+        if (processing) processing.artifact.lineageId = nextId;
+        for (const artifact of latest.values()) artifact.lineageId = nextId;
+      }
+      lineageId = nextId;
+      if (model.stats().revision !== before) notify();
+      return result;
+    },
+    observeLegacy(graph, options) { model.observeLegacy(graph, options); },
+    recordActivity(event) { model.recordActivity(event); },
+    setSessions(sessions) { model.setSessions(sessions); },
+    snapshot(options) {
+      const snapshot = model.snapshot(options);
+      // Current queue status must not be mixed into a historical checkpoint.
+      if (!options?.checkpointId) {
+        snapshot.coverage.parsing = stats();
+        snapshot.coverage.deferred.artifacts += deferred.size + undispatched.size + queue.size + (active ? 1 : 0);
+        snapshot.coverage.unavailable += [...deferred.values()].filter(item => item.reason.startsWith('parse.')).length;
+        snapshot.coverage.truncated ||= deferred.size > 0 || undispatched.size > 0 || errors.omitted > 0;
+      }
+      return snapshot;
+    },
+    stats,
+    checkpoint(options) { return model.checkpoint(options); },
+    async whenIdle() {
+      while (active || queue.size) { pump(); if (active) await active; }
+    },
+    async close() {
+      closed = true;
+      queue.clear();
+      deferred.clear();
+      undispatched.clear();
+      processing?.controller.abort();
+      try { await inventory.close(); } catch { failure('inventory.close_failed'); }
+      await active;
+    },
+  };
+}

package/runtime/visualizers/blocks.mjs

@@ -0,0 +1,5 @@
+import { structureScene } from './structure.mjs';
+export const blocks = {
+  id: 'graphlin.blocks', name: 'Blocks', renderer: 'graphlin-scene',
+  project: ({ model, settings }) => structureScene(model, settings),
+};

package/runtime/visualizers/c4.mjs

@@ -0,0 +1,52 @@
+import { structureScene, aggregateEdges, sceneKind, emptyScene } from './structure.mjs';
+
+const LEVELS = {
+  context: new Set(['system', 'external_system', 'actor', 'person', 'context']),
+  applications: new Set(['application', 'datastore', 'container']),
+  components: new Set(['component']),
+};
+const KINDS = { application: 'service', container: 'service', datastore: 'datastore',
+  component: 'service', actor: 'client', person: 'client', external_system: 'external', system: 'group' };
+
+export function c4Scene(model, settings = {}) {
+  if (settings.level === 'code') return structureScene(model, settings, { flat: true });
+  const level = LEVELS[settings.level] || LEVELS.applications;
+  const byId = new Map(model.entities.map(entity => [entity.id, entity]));
+  const boundaries = model.interpretations.filter(value =>
+    level.has(value.kind) && value.validity === 'current' && value.support === 'supported' &&
+    value.classification === 'accepted' && value.sourceRefs?.length &&
+    value.entityIds?.some(id => byId.has(id)));
+  if (!boundaries.length) {
+    const scene = structureScene(model, { ...settings, depth: 0 });
+    scene.coverage.label = 'Source scopes; application and responsibility boundaries unknown';
+    scene.groups.forEach(group => { group.style = 'unknown'; });
+    scene.nodes.forEach(node => { node.style = 'unknown'; });
+    return scene;
+  }
+  const scene = emptyScene(), represented = new Set();
+  for (const boundary of boundaries.slice(0, 63)) {
+    const members = boundary.entityIds.filter(id => byId.has(id)).slice(0, 256);
+    members.forEach(id => represented.add(id));
+    const expanded = settings.expanded?.includes(members[0]);
+    scene.groups.push({
+      id: `c4.${boundary.id}`, entityIds: members, label: boundary.label, collapsed: !expanded,
+      kind: sceneKind(KINDS[boundary.kind] || 'group'), membershipId: boundary.id,
+    });
+    if (expanded) for (const id of members) {
+      if (scene.nodes.length + scene.groups.length >= 255 || scene.nodes.some(node => node.entityId === id)) continue;
+      const entity = byId.get(id);
+      scene.nodes.push({ id, entityId: id, label: entity.label, kind: sceneKind(entity.kind), parentId: `c4.${boundary.id}` });
+    }
+  }
+  const unknown = model.entities.filter(entity => !represented.has(entity.id)).slice(0, 256);
+  if (unknown.length) scene.groups.push({
+    id: 'c4.unknown', entityIds: unknown.map(entity => entity.id), label: 'Responsibility unknown',
+    kind: 'unknown', collapsed: true, style: 'unknown',
+  });
+  scene.coverage = { shown: scene.groups.length, total: model.entities.length,
+    truncated: represented.size + unknown.length < model.entities.length || boundaries.length > 63,
+    label: 'Supported interpretations; source does not establish runtime hosting' };
+  return aggregateEdges(model, scene);
+}
+export const c4 = { id: 'graphlin.c4', name: 'C4', renderer: 'graphlin-scene',
+  project: ({ model, settings }) => c4Scene(model, settings) };

package/runtime/visualizers/changes.mjs

@@ -0,0 +1,24 @@
+import { compareCheckpoint } from '../model/changes.mjs';
+import { structureScene } from './structure.mjs';
+
+export function changesScene(model, settings = {}, baseline) {
+  if (!baseline || baseline.projectId !== model.projectId || baseline.sequence > model.sequence) {
+    const scene = structureScene(model, settings);
+    scene.coverage.label = 'Choose a retained checkpoint as the task baseline';
+    return scene;
+  }
+  const completeCoverage = value => ({ ...value,
+    coverage: { ...value.coverage, enumerations: value.coverage?.enumerations || [] } });
+  const changes = compareCheckpoint(completeCoverage(baseline), completeCoverage(model), settings.baseline);
+  const styles = new Map();
+  for (const [key, style] of Object.entries({
+    discoveries: 'discovered', creations: 'added', modifications: 'modified', removals: 'removed', invalidations: 'stale',
+  })) for (const value of changes[key]) styles.set((value.after || value).id, style);
+  const scene = structureScene(model, settings, { styles });
+  scene.coverage.label = `Since revision ${baseline.revision}: ${changes.discoveries.length} discovered, ` +
+    `${changes.creations.length} created, ${changes.modifications.length} modified, ` +
+    `${changes.removals.length} removed, ${changes.invalidations.length} invalidated`;
+  return scene;
+}
+export const changes = { id: 'graphlin.changes', name: 'Changes', renderer: 'graphlin-scene',
+  project: ({ model, settings, baseline }) => changesScene(model, settings, baseline) };

package/runtime/visualizers/code.mjs

@@ -0,0 +1,5 @@
+import { structureScene } from './structure.mjs';
+export const code = {
+  id: 'graphlin.code', name: 'Code', renderer: 'graphlin-scene',
+  project: ({ model, settings }) => structureScene(model, settings, { flat: true }),
+};

package/runtime/visualizers/index.mjs

@@ -0,0 +1,23 @@
+import { code } from './code.mjs';
+import { blocks } from './blocks.mjs';
+import { c4 } from './c4.mjs';
+import { changes } from './changes.mjs';
+import { timeline } from './timeline.mjs';
+import { validateScene } from '../extensions/scene.mjs';
+
+export const BUILTIN_VIEWS = Object.freeze([code, blocks, c4, changes, timeline]);
+
+export function createBuiltin(id, context) {
+  const definition = BUILTIN_VIEWS.find(view => view.id === id);
+  if (!definition) throw new Error('unknown_visualizer');
+  const custom = definition.create?.(context);
+  let disposed = false;
+  return {
+    update(input) {
+      if (disposed) throw new Error('extension_disposed');
+      if (custom) return custom.update(input);
+      return { kind: 'scene', scene: validateScene(definition.project(input), { model: input.model }) };
+    },
+    dispose() { disposed = true; custom?.dispose(); },
+  };
+}

package/runtime/visualizers/structure.mjs

@@ -0,0 +1,120 @@
+import { SCENE_KINDS, EDGE_KINDS } from '../extensions/scene.mjs';
+
+export const emptyScene = () => ({ sceneVersion: 1, nodes: [], groups: [], edges: [] });
+export const sceneKind = kind => SCENE_KINDS.includes(kind) ? kind :
+  ({ method: 'function', namespace: 'module', enum: 'class', type_alias: 'interface',
+    variable: 'module', directory: 'package', file: 'module', project: 'package' }[kind] || 'unknown');
+
+export function entityIndex(model) {
+  const byId = new Map(model.entities.map(entity => [entity.id, entity]));
+  const children = new Map();
+  for (const entity of byId.values()) {
+    const parent = byId.has(entity.parentId) ? entity.parentId : null;
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push(entity.id);
+  }
+  return { byId, children };
+}
+
+export function ancestors(id, byId) {
+  const result = [], seen = new Set([id]);
+  let parent = byId.get(id)?.parentId;
+  while (byId.has(parent) && !seen.has(parent)) {
+    seen.add(parent); result.push(parent); parent = byId.get(parent).parentId;
+  }
+  return result;
+}
+
+function descendants(id, children) {
+  const result = [], pending = [id], seen = new Set();
+  for (let cursor = 0; cursor < pending.length; cursor++) {
+    const next = pending[cursor];
+    if (seen.has(next)) continue;
+    seen.add(next); result.push(next);
+    pending.push(...(children.get(next) || []));
+  }
+  return result;
+}
+
+export function aggregateEdges(model, scene) {
+  const owner = new Map();
+  // The most specific visible item owns an endpoint. Expanded group membership
+  // includes descendants, but must not hide a visible child's own relationships.
+  for (const group of scene.groups) for (const id of group.entityIds) owner.set(id, group.id);
+  for (const node of scene.nodes) owner.set(node.entityId, node.id);
+  const combined = new Map();
+  for (const relation of model.relations) {
+    const source = owner.get(relation.source), target = owner.get(relation.target);
+    if (!source || !target || source === target || relation.kind === 'contains' ||
+      !EDGE_KINDS.includes(relation.kind)) continue;
+    const key = JSON.stringify([source, target, relation.kind, relation.validity]);
+    if (!combined.has(key)) {
+      if (combined.size >= 768) continue;
+      combined.set(key, {
+        id: `link.${combined.size}`, source, target, kind: relation.kind, relationIds: [],
+        style: relation.validity === 'current' ? 'default' : 'stale',
+      });
+    }
+    const edge = combined.get(key);
+    if (edge.relationIds.length < 256) edge.relationIds.push(relation.id);
+  }
+  scene.edges = [...combined.values()].map(edge => ({
+    ...edge, count: edge.relationIds.length,
+    label: `${edge.kind.replaceAll('_', ' ')}${edge.relationIds.length > 1 ? ` (${edge.relationIds.length})` : ''}`,
+  }));
+  return scene;
+}
+
+export function structureScene(model, settings = {}, { flat = false, styles = new Map() } = {}) {
+  const scene = emptyScene();
+  const { byId, children } = entityIndex(model);
+  const expanded = new Set(settings.expanded || []);
+  const needle = (settings.query || '').toLowerCase();
+  const types = settings.kinds ? new Set(settings.kinds) : null;
+  const filtering = Boolean(needle || types);
+  const matches = new Set(model.entities.filter(entity =>
+    (!needle || `${entity.label} ${entity.qualifiedName || ''}`.toLowerCase().includes(needle)) &&
+    (!types || types.has(entity.kind))).map(entity => entity.id));
+  const relevant = new Set(matches);
+  if (filtering) for (const id of matches) for (const parent of ancestors(id, byId)) {
+    relevant.add(parent); expanded.add(parent);
+  }
+  const roots = settings.scope && byId.has(settings.scope) ? [settings.scope] : (children.get(null) || []);
+  const pending = roots.map(id => ({ id, parentId: null, depth: 0 }));
+  const visited = new Set();
+  while (pending.length && scene.nodes.length + scene.groups.length < 256) {
+    const { id, parentId, depth } = pending.shift();
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const entity = byId.get(id);
+    if (!entity || (filtering && !relevant.has(id))) continue;
+    const childIds = children.get(id) || [];
+    const style = styles.get(id) || (entity.validity !== 'current' ? 'stale' :
+      entity.classification === 'tentative' ? 'tentative' : 'default');
+    if (!flat && childIds.length && scene.groups.length < 64) {
+      const members = descendants(id, children);
+      const collapsed = !(expanded.has(id) || (!settings.collapsed?.includes(id) && depth < (settings.depth ?? 1)));
+      const changed = members.filter(member => styles.has(member));
+      scene.groups.push({
+        id, entityIds: members.slice(0, 256),
+        label: changed.length ? `${entity.label.slice(0, 200)} (${changed.length} changed)` : entity.label,
+        kind: sceneKind(entity.kind), ...(parentId ? { parentId } : {}), collapsed,
+        style: styles.get(id) || (changed.length ? styles.get(changed[0]) : style),
+      });
+      if (!collapsed) pending.push(...childIds.map(child => ({ id: child, parentId: id, depth: depth + 1 })));
+    } else {
+      if (!filtering || matches.has(id)) scene.nodes.push({
+        id, entityId: id, label: entity.label, kind: sceneKind(entity.kind), style,
+        ...(parentId ? { parentId } : {}),
+      });
+      if (flat || childIds.length) pending.push(...childIds.map(child => ({ id: child, parentId, depth: depth + 1 })));
+    }
+  }
+  scene.coverage = {
+    shown: scene.nodes.length + scene.groups.length, total: model.entities.length,
+    truncated: pending.length > 0 || scene.groups.some(group =>
+      (children.get(group.id) || []).length > 0 && group.entityIds.length === 256),
+    label: 'Source structure; discovery may be incomplete',
+  };
+  return aggregateEdges(model, scene);
+}

package/runtime/visualizers/timeline.mjs

@@ -0,0 +1,66 @@
+// First-party custom renderer. It consumes the same update/dispose lifecycle as
+// scene projectors and works when entities and relations are both empty.
+export function timelineRows(model, settings = {}) {
+  const query = (settings.query || '').toLowerCase();
+  const rows = model.activity.filter(event => !settings.session || event.sessionId === settings.session)
+    .filter(event => !query || `${event.kind} ${event.toolCategory} ${event.agentId || ''}`.toLowerCase().includes(query))
+    .slice(-200).map(event => ({
+      id: event.id, sequence: event.sequence, at: event.at ?? event.timestamp,
+      lane: event.agentId || event.sessionId || 'Unattributed',
+      label: `${event.toolCategory || 'Activity'} · ${(event.kind || 'observation').replaceAll('.', ' ')}`,
+      outcome: event.outcome || 'unresolved', attribution: event.attribution || 'unknown',
+      toolCallId: event.toolCallId, entityIds: event.entityIds || [],
+    })).sort((a, b) => a.sequence - b.sequence || a.id.localeCompare(b.id));
+  // Pair only explicitly correlated observations. A pending attempt without a
+  // terminal event remains unresolved; parallel tool IDs remain separate.
+  const outcomes = new Map();
+  for (const row of rows) if (row.toolCallId && !['pending', 'unresolved', 'observed'].includes(row.outcome))
+    outcomes.set(`${row.lane}:${row.toolCallId}`, row.outcome);
+  return rows.map(row => ({ ...row, outcome: row.outcome === 'pending'
+    ? outcomes.get(`${row.lane}:${row.toolCallId}`) || 'unresolved' : row.outcome }));
+}
+
+export function createTimeline({ root, select = () => {} }) {
+  const document = root.ownerDocument;
+  const element = (tag, text, className) => {
+    const node = document.createElement(tag);
+    if (text !== undefined) node.textContent = text;
+    if (className) node.className = className;
+    return node;
+  };
+  let disposed = false, lastSequence = null;
+  return {
+    update({ model, settings = {} }) {
+      if (disposed) throw new Error('extension_disposed');
+      const focusedId = document.activeElement?.dataset?.activityId;
+      const rows = timelineRows(model, settings);
+      const heading = element('p', `${rows.length} ordered observations. Parallel lanes use recorded agent or session attribution.`, 'timeline-note');
+      const list = element('ol', undefined, 'timeline-events');
+      list.setAttribute('aria-label', 'Agent and tool observations in sequence order');
+      let focus;
+      for (const row of rows) {
+        const item = element('li', undefined, 'timeline-event');
+        item.dataset.outcome = row.outcome;
+        const time = element('time', Number.isFinite(Date.parse(row.at)) ? new Date(row.at).toLocaleTimeString() : 'Time unknown');
+        const button = element('button', row.label);
+        button.setAttribute('type', 'button');
+        button.dataset.activityId = row.id;
+        button.setAttribute('aria-label', `${row.label}. ${row.outcome}. ${row.entityIds.length ? 'Inspect linked evidence' : 'No linked entity'}.`);
+        button.addEventListener('click', () => select({ activityId: row.id, entityId: row.entityIds[0] || null }));
+        if (focusedId === row.id) focus = button;
+        item.append(time, element('span', row.lane, 'timeline-lane'), button,
+          element('span', row.outcome, 'timeline-outcome'),
+          element('span', `${row.attribution} attribution`, 'timeline-attribution'));
+        list.append(item);
+      }
+      if (!rows.length) list.append(element('li', 'No observations at this position. Select Live to follow captured work.'));
+      root.replaceChildren(heading, list);
+      focus?.focus({ preventScroll: true });
+      if (settings.follow && lastSequence !== null && model.sequence > lastSequence) list.children[list.children.length - 1]?.scrollIntoView({ block: 'nearest' });
+      lastSequence = model.sequence;
+      return { kind: 'custom', status: 'ready', itemCount: rows.length };
+    },
+    dispose() { disposed = true; root.replaceChildren(); },
+  };
+}
+export const timeline = { id: 'graphlin.timeline', name: 'Activity timeline', renderer: 'custom', create: createTimeline };