@stephen-netu/design-system 0.1.0

package/src/entity-graph-view/WorldView.svelte

@@ -0,0 +1,171 @@
+<script lang="ts">
+  import type { WorldSnapshot, EntityFilter } from './types';
+  import { snapshotToGraphSchema, snapshotToMetrics, snapshotToTimeline, entityStateStr, filterEntities } from './types';
+  import type { GraphSchema } from '../n0-node-graph/types';
+  import type { Tab } from '../u0-primitives/tabs/tabs-types';
+  import type { MetricCardProps, TimelineEntry } from '../d0-data-viz/types';
+  import GraphEditor from '../n0-node-graph/GraphEditor.svelte';
+  import MetricCard from '../d0-data-viz/MetricCard.svelte';
+  import Timeline from '../d0-data-viz/Timeline.svelte';
+  import Tabs from '../u0-primitives/tabs/Tabs.svelte';
+
+  interface WorldViewProps {
+    snapshot: WorldSnapshot;
+    filter?: EntityFilter;
+    readonly?: boolean;
+    'aria-label'?: string;
+  }
+
+  let {
+    snapshot,
+    filter,
+    readonly = false,
+    'aria-label': ariaLabel = 'Entity Graph View',
+  }: WorldViewProps = $props();
+
+  // Derived data for visualizations
+  let graphSchema = $derived(snapshotToGraphSchema(snapshot));
+  let metrics = $derived(snapshotToMetrics(snapshot));
+  let timelineEntries = $derived(snapshotToTimeline(snapshot));
+
+  // Filtered entity/edge counts
+  let entityCount = $derived(
+    filter
+      ? filterEntities(Object.values(snapshot.entities), filter).length
+      : Object.keys(snapshot.entities).length
+  );
+  let edgeCount = $derived(Object.keys(snapshot.edges).length);
+
+  // Tab configuration — MUST be $derived so labels react to count changes
+  let tabs = $derived<Tab[]>([
+    { id: 'graph', label: `Graph (${entityCount})` },
+    { id: 'metrics', label: `Metrics (${metrics.length})` },
+    { id: 'timeline', label: `Timeline (${timelineEntries.length})` },
+  ]);
+  let activeTab = $state('graph');
+</script>
+
+<div class="entity-graph-view" role="region" aria-label={ariaLabel}>
+  <div class="entity-graph-view__header">
+    <h2 class="entity-graph-view__title">
+      Entity Graph
+      <span class="entity-graph-view__sequence">#{snapshot.sequence}</span>
+    </h2>
+    <div class="entity-graph-view__stats">
+      <span class="entity-graph-view__stat">{entityCount} entities</span>
+      <span class="entity-graph-view__stat">{edgeCount} edges</span>
+    </div>
+  </div>
+
+  <Tabs {tabs} bind:activeId={activeTab} />
+
+  <div class="entity-graph-view__content">
+    {#if activeTab === 'graph'}
+      <div class="entity-graph-view__graph">
+        <GraphEditor
+          schema={graphSchema}
+          readonly={readonly}
+          snapToGrid={false}
+        />
+      </div>
+    {:else if activeTab === 'metrics'}
+      <div class="entity-graph-view__metrics">
+        {#if metrics.length === 0}
+          <p class="entity-graph-view__empty">No scalar metrics available</p>
+        {:else}
+          <div class="entity-graph-view__metrics-grid">
+            {#each metrics as metric (metric.label)}
+              <MetricCard {...metric} />
+            {/each}
+          </div>
+        {/if}
+      </div>
+    {:else if activeTab === 'timeline'}
+      <div class="entity-graph-view__timeline">
+        {#if timelineEntries.length === 0}
+          <p class="entity-graph-view__empty">No state transitions recorded</p>
+        {:else}
+          <Timeline entries={timelineEntries} orientation="vertical" />
+        {/if}
+      </div>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .entity-graph-view {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    min-height: 400px;
+    background: var(--color-surface, #1a1a1a);
+    border-radius: var(--radius-lg, 8px);
+    overflow: hidden;
+  }
+
+  .entity-graph-view__header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 16px 20px;
+    border-bottom: 1px solid var(--border-default, #333);
+  }
+
+  .entity-graph-view__title {
+    font-size: 18px;
+    font-weight: 600;
+    color: var(--color-text-primary, #e5e5e5);
+    margin: 0;
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+  }
+
+  .entity-graph-view__sequence {
+    font-size: 14px;
+    font-weight: 400;
+    color: var(--color-text-secondary, #888);
+  }
+
+  .entity-graph-view__stats {
+    display: flex;
+    gap: 16px;
+  }
+
+  .entity-graph-view__stat {
+    font-size: 13px;
+    color: var(--color-text-secondary, #888);
+  }
+
+  .entity-graph-view__content {
+    flex: 1;
+    overflow: auto;
+    padding: 16px;
+  }
+
+  .entity-graph-view__graph {
+    height: 100%;
+    min-height: 300px;
+  }
+
+  .entity-graph-view__metrics {
+    padding: 8px;
+  }
+
+  .entity-graph-view__metrics-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+    gap: 16px;
+  }
+
+  .entity-graph-view__timeline {
+    padding: 8px;
+  }
+
+  .entity-graph-view__empty {
+    color: var(--color-text-secondary, #888);
+    font-size: 14px;
+    text-align: center;
+    padding: 40px;
+  }
+</style>

package/src/entity-graph-view/index.ts

@@ -0,0 +1,6 @@
+// Entity Graph View — SOVEREIGN Entity Graph Visualization
+// Exports types, adapters, and components for visualizing entity graphs
+// from SOVEREIGN's m0-primitives module
+
+export * from './types';
+export { default as WorldView } from './WorldView.svelte';

package/src/entity-graph-view/types.ts

@@ -0,0 +1,364 @@
+// Entity Graph View — SOVEREIGN Entity Graph Visualization Types
+// Maps m0-primitives entity types to LEAP visualization components
+//
+// IMPORTANT: These types match the serde serialization output from Rust.
+// Rust uses snake_case fields and externally tagged enum variants by default.
+
+import type { GraphSchema, NodeInstance, NodeDefinition, EdgeDefinition } from '../n0-node-graph/types';
+import type { MetricCardProps, TimelineEntry } from '../d0-data-viz/types';
+
+// === Serde-compatible SOVEREIGN Entity Types ===
+//
+// Rust newtype wrappers (EntityId, EdgeId) serialize as plain strings.
+// Rust enums serialize as externally tagged: { "Custom": "foo" }, { "Active": null }
+// Rust BTreeMap serializes as plain JSON object, not TS Map.
+// Rust BTreeSet serializes as JSON array.
+// Rust u64 serializes as JSON number.
+
+export type EntityId = string;
+export type EdgeId = string;
+
+// Enums — externally tagged per serde default
+export type EntityType = { Custom: string };
+export type RelationshipType = { Custom: string };
+export type MetricType = { Custom: string };
+
+export type EntityState =
+  | { Active: null }
+  | { Inactive: null }
+  | { Degraded: null }
+  | { Critical: null }
+  | { Pending: null }
+  | { Resolved: null }
+  | { Custom: string };
+
+export type MetricValue =
+  | { Scalar: number }
+  | { Distribution: number[] }
+  | { TimeSeries: [number, number][] };
+
+// === Core Domain Structs (snake_case matches Rust) ===
+
+export interface WorldEntity {
+  id: EntityId;
+  entity_type: EntityType;
+  canonical_name: string;
+  display_name: string;
+  properties: Record<string, unknown>;
+  state: EntityState;
+  created_sequence: number;
+  updated_sequence: number;
+  tags: string[];
+}
+
+export interface WorldEdge {
+  id: EdgeId;
+  source: EntityId;
+  target: EntityId;
+  relationship: RelationshipType;
+  properties: Record<string, unknown>;
+  weight: number;
+  created_sequence: number;
+}
+
+export interface WorldMetric {
+  entity_id: EntityId;
+  metric_type: MetricType;
+  value: MetricValue;
+  unit: string;
+  timestamp_sequence: number;
+  source: string;
+}
+
+export interface StateTransition {
+  entity_id: EntityId;
+  from_state: EntityState;
+  to_state: EntityState;
+  trigger: string;
+  sequence: number;
+  metadata: Record<string, unknown>;
+}
+
+export interface WorldSnapshot {
+  sequence: number;
+  // BTreeMap serializes as plain JSON object
+  entities: Record<EntityId, WorldEntity>;
+  edges: Record<EdgeId, WorldEdge>;
+  // BTreeMap<EntityId, BTreeMap<String, Vec<WorldMetric>>>
+  metrics: Record<EntityId, Record<string, WorldMetric[]>>;
+  transitions: StateTransition[];
+}
+
+// === Delta / Anomaly / MetricDelta (for streaming updates) ===
+
+/** The delta between two snapshots — used for incremental updates. */
+export interface WorldDelta {
+  since_sequence: number;
+  until_sequence: number;
+  added_entities: EntityId[];
+  modified_entities: EntityId[];
+  removed_entities: EntityId[];
+  added_edges: EdgeId[];
+  removed_edges: EdgeId[];
+  // BTreeMap<EntityId, Vec<WorldMetric>>
+  new_metrics: Record<EntityId, WorldMetric[]>;
+  new_transitions: StateTransition[];
+}
+
+/** A detected anomaly on an entity metric. */
+export interface Anomaly {
+  entity_id: EntityId;
+  metric_type: MetricType;
+  description: string;
+  severity: number;
+  sequence: number;
+}
+
+/** The change in a metric over a window. */
+export interface MetricDelta {
+  entity_id: EntityId;
+  metric_type: MetricType;
+  start_value: number;
+  end_value: number;
+  absolute_change: number;
+  percent_change: number;
+  window_start: number;
+  window_end: number;
+}
+
+// === Enum Extractors ===
+
+/** Extract string value from externally-tagged EntityType */
+export function entityTypeStr(t: EntityType): string {
+  return t.Custom;
+}
+
+/** Extract string value from externally-tagged RelationshipType */
+export function relationshipTypeStr(t: RelationshipType): string {
+  return t.Custom;
+}
+
+/** Extract string value from externally-tagged MetricType */
+export function metricTypeStr(t: MetricType): string {
+  return t.Custom;
+}
+
+/** Extract state string from externally-tagged EntityState */
+export function entityStateStr(s: EntityState): string {
+  if ('Active' in s) return 'active';
+  if ('Inactive' in s) return 'inactive';
+  if ('Degraded' in s) return 'degraded';
+  if ('Critical' in s) return 'critical';
+  if ('Pending' in s) return 'pending';
+  if ('Resolved' in s) return 'resolved';
+  if ('Custom' in s) return s.Custom;
+  return 'unknown';
+}
+
+/** Extract scalar value from MetricValue, if scalar */
+export function metricValueScalar(v: MetricValue): number | null {
+  if ('Scalar' in v) return v.Scalar;
+  return null;
+}
+
+/** Extract latest value from MetricValue */
+export function metricValueLatest(v: MetricValue): number | null {
+  if ('Scalar' in v) return v.Scalar;
+  if ('Distribution' in v) {
+    const d = v.Distribution;
+    return d.length > 0 ? d[d.length - 1] : null;
+  }
+  if ('TimeSeries' in v) {
+    const ts = v.TimeSeries;
+    return ts.length > 0 ? ts[ts.length - 1][1] : null;
+  }
+  return null;
+}
+
+// === State Color Map ===
+
+export const STATE_COLORS: Record<string, string> = {
+  active: '#22c55e',
+  inactive: '#6b7280',
+  degraded: '#f59e0b',
+  critical: '#ef4444',
+  pending: '#3b82f6',
+  resolved: '#10b981',
+};
+
+// === Adapters ===
+
+/**
+ * Convert WorldEntity to NodeInstance for n0-node-graph.
+ * EntityId is a string, so id maps directly.
+ */
+export function entityToNodeInstance(
+  entity: WorldEntity,
+  position: { x: number; y: number } = { x: 0, y: 0 }
+): NodeInstance {
+  return {
+    id: entity.id,
+    kind: entityTypeStr(entity.entity_type),
+    position,
+    size: { width: 200, height: 100 },
+    data: {
+      display_name: entity.display_name,
+      canonical_name: entity.canonical_name,
+      state: entityStateStr(entity.state),
+      tags: entity.tags,
+      ...entity.properties,
+    },
+    collapsed: false,
+  };
+}
+
+/**
+ * Convert WorldEdge to EdgeDefinition for n0-node-graph.
+ */
+export function edgeToEdgeDefinition(edge: WorldEdge): EdgeDefinition {
+  return {
+    id: edge.id,
+    sourceNodeId: edge.source,
+    sourcePortId: 'output',
+    targetNodeId: edge.target,
+    targetPortId: 'input',
+    metadata: {
+      relationship: relationshipTypeStr(edge.relationship),
+      weight: edge.weight,
+      ...edge.properties,
+    },
+  };
+}
+
+/**
+ * Generate NodeDefinition for an entity type.
+ * One definition per unique entity_type in the snapshot.
+ */
+export function entityTypeToNodeDefinition(entityType: string): NodeDefinition {
+  return {
+    kind: entityType,
+    label: entityType.charAt(0).toUpperCase() + entityType.slice(1),
+    description: `${entityType} entity`,
+    ports: [
+      { id: 'input', label: 'In', type: 'system:edge:default', direction: 'input', required: false, maxConnections: -1 },
+      { id: 'output', label: 'Out', type: 'system:edge:default', direction: 'output', required: false, maxConnections: -1 },
+    ],
+    metadata: {},
+  };
+}
+
+/**
+ * Convert WorldSnapshot to GraphSchema with ELK-compatible layout hints.
+ * Positions are set to 0,0 — use elkjs for layout before rendering.
+ */
+export function snapshotToGraphSchema(snapshot: WorldSnapshot): GraphSchema {
+  // Collect unique entity types for node definitions
+  const typeSet = new Set<string>();
+  Object.values(snapshot.entities).forEach(e => {
+    typeSet.add(entityTypeStr(e.entity_type));
+  });
+  const nodeDefinitions: NodeDefinition[] = Array.from(typeSet).sort().map(entityTypeToNodeDefinition);
+
+  // Create nodes at origin — layout engine positions them
+  const nodes: NodeInstance[] = Object.values(snapshot.entities).map(e =>
+    entityToNodeInstance(e, { x: 0, y: 0 })
+  );
+
+  // Create edges
+  const edges: EdgeDefinition[] = Object.values(snapshot.edges).map(edgeToEdgeDefinition);
+
+  return {
+    id: `entity-graph-${snapshot.sequence}`,
+    name: `Entity Graph #${snapshot.sequence}`,
+    version: '1.0.0',
+    nodeDefinitions,
+    nodes,
+    edges,
+  };
+}
+
+/**
+ * Extract latest scalar metrics as MetricCardProps.
+ */
+export function snapshotToMetrics(snapshot: WorldSnapshot): MetricCardProps[] {
+  const cards: MetricCardProps[] = [];
+
+  for (const [_entityId, metricMap] of Object.entries(snapshot.metrics)) {
+    for (const [metricTypeKey, metrics] of Object.entries(metricMap)) {
+      if (metrics.length === 0) continue;
+
+      // Find latest by timestamp_sequence
+      const sorted = [...metrics].sort((a, b) => a.timestamp_sequence - b.timestamp_sequence);
+      const latest = sorted[sorted.length - 1];
+      const scalar = metricValueLatest(latest.value);
+      if (scalar === null) continue;
+
+      // Compute trend from last two values
+      let trend: 'up' | 'down' | 'flat' | undefined;
+      if (sorted.length >= 2) {
+        const prev = metricValueLatest(sorted[sorted.length - 2].value);
+        if (prev !== null) {
+          trend = scalar > prev ? 'up' : scalar < prev ? 'down' : 'flat';
+        }
+      }
+
+      cards.push({
+        label: metricTypeKey.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+        value: scalar.toFixed(2),
+        unit: latest.unit,
+        trend,
+        size: 'default',
+      });
+    }
+  }
+
+  return cards;
+}
+
+/**
+ * Convert StateTransitions to TimelineEntries.
+ */
+export function snapshotToTimeline(snapshot: WorldSnapshot): TimelineEntry[] {
+  return [...snapshot.transitions]
+    .sort((a, b) => a.sequence - b.sequence)
+    .map(t => ({
+      id: `transition-${t.sequence}-${t.entity_id}`,
+      timestamp: `Seq ${t.sequence}`,
+      label: `${entityStateStr(t.from_state)} → ${entityStateStr(t.to_state)}`,
+      description: `${t.entity_id}: ${t.trigger}`,
+      color: STATE_COLORS[entityStateStr(t.to_state)] ?? '#6b7280',
+    }));
+}
+
+// === Filter ===
+
+export interface EntityFilter {
+  entity_types?: string[];
+  states?: string[];
+  tags_any?: string[];
+  tags_all?: string[];
+  name_contains?: string;
+}
+
+export function filterEntities(entities: WorldEntity[], filter: EntityFilter): WorldEntity[] {
+  return entities.filter(entity => {
+    if (filter.entity_types?.length && !filter.entity_types.includes(entityTypeStr(entity.entity_type))) {
+      return false;
+    }
+    if (filter.states?.length && !filter.states.includes(entityStateStr(entity.state))) {
+      return false;
+    }
+    if (filter.tags_any?.length && !filter.tags_any.some(t => entity.tags.includes(t))) {
+      return false;
+    }
+    if (filter.tags_all?.length && !filter.tags_all.every(t => entity.tags.includes(t))) {
+      return false;
+    }
+    if (filter.name_contains &&
+        !entity.canonical_name.includes(filter.name_contains) &&
+        !entity.display_name.includes(filter.name_contains)) {
+      return false;
+    }
+    return true;
+  });
+}

package/src/epistemic/index.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './utils.js';

package/src/epistemic/types.ts

@@ -0,0 +1,134 @@
+// @kos/design-system — Epistemic transparency types
+// Derived from LEAP-EPISTEMIC-TRANSPARENCY-SPEC.md
+
+// --- ASSAY ---
+export interface AssayClearanceView {
+  checkpoint: 'PreIsr' | 'PreMettle' | 'PreEffector' | 'PreKnowledge';
+  gate: 'Cleared' | 'Blocked';
+  severity: 'None' | 'Minor' | 'Medium' | 'High' | 'Critical';
+  weightedSum: number;            // 0.0–1.0
+  signals: AssaySignalView[];
+  computedAt: number;             // deterministic tick
+  isDegraded: boolean;
+}
+
+export interface AssaySignalView {
+  id: 'SaeClarity' | 'SchemaValid' | 'RiskTier' | 'SourceCredibility'
+    | 'SemanticCoherence' | 'CapabilityCheck' | 'FeatureCoverage' | 'NoveltyGate';
+  result: 'Pass' | 'Fail' | 'Unavailable';
+  confidence: number | null;
+  isHardGate: boolean;
+  reason?: string;
+}
+
+// --- ALLAY ---
+export interface AllayStageView {
+  stage: 0 | 1 | 2 | 3 | 4 | 5;
+  confidence: number;             // 0.0–1.0
+  stageName: 'Propose' | 'Parse' | 'Authorize' | 'Execute' | 'Trace' | 'Replicate';
+}
+
+// Mapping from assay_confidence (u8, 0-255) to stage:
+// 0-50:    Stage 0 (Propose)
+// 51-100:  Stage 1 (Parse)
+// 101-150: Stage 2 (Authorize)
+// 151-190: Stage 3 (Execute)
+// 191-230: Stage 4 (Trace)
+// 231-255: Stage 5 (Replicate)
+export function confidenceToStage(confidence: number): AllayStageView {
+  const stage: 0 | 1 | 2 | 3 | 4 | 5 =
+    confidence <= 50 ? 0 :
+    confidence <= 100 ? 1 :
+    confidence <= 150 ? 2 :
+    confidence <= 190 ? 3 :
+    confidence <= 230 ? 4 : 5;
+  const names: AllayStageView['stageName'][] = ['Propose','Parse','Authorize','Execute','Trace','Replicate'];
+  return { stage, confidence: confidence / 255, stageName: names[stage] };
+}
+
+// --- EXPERT ---
+export interface ExpertIdentity {
+  name: 'Atelier' | 'Agora' | 'Ryu' | 'SOVEREIGN' | 'Agent';
+  agentId?: string;
+  domain: string;
+}
+
+// --- AVENUE ---
+// Flat step view — matches the Rust AvenueStepView struct emitted by the Tauri command.
+// Rich per-type fields are NOT present; use step_type + summary for display.
+export interface AvenueStepView {
+  step_type: 'query' | 'retrieve' | 'filter' | 'synthesize' | 'contradict' | 'verify' | string;
+  summary: string;
+}
+
+export interface AvenueTraceView {
+  steps: AvenueStepView[];
+  isPartial: boolean;
+  confidence: number;
+  session_id: string;
+}
+
+// --- PROVENANCE ---
+export type ProvenanceNodeType =
+  | 'human_draft' | 'file_source' | 'web_source' | 'assay_evaluation'
+  | 'sigchain_witness' | 'agent_research' | 'accord_replication'
+  | 'access_epoch' | 'knowledge_merge' | 'supersession';
+
+export interface ProvenanceChainNodeBase {
+  id: string;
+  timestamp: number;
+  expert: ExpertIdentity;
+  previousNodeId: string | null;
+}
+
+export type ProvenanceChainNode = ProvenanceChainNodeBase & (
+  | { type: 'human_draft'; detail: { contentHash: string } }
+  | { type: 'file_source'; detail: { filePath: string; contentHash: string } }
+  | { type: 'web_source'; detail: { url: string; sourceUrlHash: string; sectionId?: string } }
+  | { type: 'assay_evaluation'; detail: { checkpoint: string; gate: string; clearanceHash: string; weightedSum: number } }
+  | { type: 'sigchain_witness'; detail: { witnessRef: string; assayConfidence: number } }
+  | { type: 'agent_research'; detail: { sessionId: string; claimHash: string } }
+  | { type: 'accord_replication'; detail: { accordId: string; sourceRealmId: string } }
+  | { type: 'access_epoch'; detail: { accessCount: number; consolidatorId: string } }
+  | { type: 'knowledge_merge'; detail: { inputHashes: string[] } }
+  | { type: 'supersession'; detail: { supersededHash: string } }
+);
+
+// --- EPISTEMIC DETAIL ---
+export interface KnowledgeEpistemicDetail {
+  contentHash: string;
+  title: string;
+  source: string;
+  // Phase 0: Rust returns null; will be ExpertIdentity once wt-710 is wired.
+  expert?: ExpertIdentity | null;
+  allay: AllayStageView;
+  // Phase 0: Rust returns null; will be non-null once AssayClearanceFor is wired.
+  assay?: AssayClearanceView | null;
+  // Phase 0: Rust returns null; will be ProvenanceChainNode[] once wt-710 is wired.
+  provenance: ProvenanceChainNode[] | null;
+  // Phase 0: Rust returns null; will be AvenueTraceView once wt-711 is wired.
+  avenue?: AvenueTraceView | null;
+  convergence: number;
+}
+
+// --- AGGREGATE STATS ---
+export interface EpistemicStats {
+  totalKnowledge: number;
+  byStage: Record<number, number>;
+  byGate: Record<string, number>;
+  pendingReview: number;
+  averageConfidence: number;
+}
+
+// Rust-side alias (camelCase serde output from EpistemicStatsView).
+// byStage / byGate are stub empty objects until wt-710 daemon aggregate is wired.
+export type EpistemicStatsView = EpistemicStats;
+
+// --- PARADIGM ---
+export interface ParadigmDefinition {
+  id: 'spatial' | 'temporal' | 'hierarchical' | 'graph' | 'trust';
+  label: string;
+  description: string;
+  conceals: string;
+  icon: string;
+}