@company-semantics/contracts 0.1.0 → 0.2.1

package/index.ts

@@ -21,13 +21,22 @@ export type InsightConfidence = 'low' | 'medium' | 'high'
 // Invariant enforcement phases (4.0 Observe → 4.1 Stabilize → 4.2 Enforce)
 export type InvariantPhase = 'observe' | 'stabilize' | 'enforce'
 
-// System snapshot types (Living ASCII Diagram)
+// System diagram types (Living ASCII Diagram)
 // @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
 export type {
+  // Layer-based manifest (source of truth)
   FeatureStatus,
   SystemCapability,
   SystemLayer,
   SystemCapabilityManifest,
+  // Snapshot metadata
   SystemSnapshotMeta,
+  /** @deprecated Use DiagramSpec instead */
   SystemSnapshot,
+  // Graph-based diagram spec (new architecture)
+  DiagramNodeKind,
+  DiagramEdgeRelation,
+  DiagramNode,
+  DiagramEdge,
+  DiagramSpec,
 } from './system/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "repository": {
     "type": "git",

package/system/README.md

@@ -0,0 +1,46 @@
+# system/
+
+## Purpose
+
+TypeScript types for the Living ASCII System Diagram feature.
+Defines the semantic contract between backend (producer) and site (renderer).
+
+**Key architecture:**
+- Backend owns MEANING (produces `DiagramSpec` with nodes/edges)
+- Client owns RENDERING (ASCII, SVG, canvas, etc.)
+- No diagram artifacts committed — runtime rendering only
+
+## Invariants
+
+- Types only — no runtime code
+- Schema changes require coordinated releases across repos
+- No render hints in contracts — renderers decide presentation independently
+- `layer` metadata is semantic grouping, not layout instruction
+
+## Public API
+
+### Source model (layer-based)
+- `FeatureStatus` — 'prod' | 'experimental' | 'disabled'
+- `SystemCapability` — individual feature definition
+- `SystemLayer` — logical layer grouping
+- `SystemCapabilityManifest` — full manifest structure (YAML representation)
+
+### Diagram graph (new architecture)
+- `DiagramNodeKind` — 'layer' | 'feature' | 'artifact'
+- `DiagramEdgeRelation` — 'contains' | 'flows_to' | 'depends_on'
+- `DiagramNode` — semantic node with optional layer grouping
+- `DiagramEdge` — semantic relationship between nodes
+- `DiagramSpec` — complete graph that crosses system boundaries
+
+### Metadata (retained for compatibility)
+- `SystemSnapshotMeta` — generation metadata
+- `SystemSnapshot` — **deprecated**, use DiagramSpec instead
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics (backend), company-semantics-site
+
+## Specification
+
+See [LIVING_ASCII_DIAGRAM_SPEC.md](../docs/LIVING_ASCII_DIAGRAM_SPEC.md) for the canonical system definition.

package/system/diagram.ts

@@ -0,0 +1,72 @@
+/**
+ * Diagram Specification Types
+ *
+ * Graph-based semantic model for system diagrams.
+ * These types define MEANING, not presentation.
+ *
+ * Key invariants:
+ * - No render hints — renderers decide presentation independently
+ * - layer metadata is semantic grouping, not layout instruction
+ * - Graphs can be rendered as ASCII, SVG, canvas, or any future format
+ *
+ * @see ../docs/LIVING_ASCII_DIAGRAM_SPEC.md
+ */
+
+import type { FeatureStatus } from './index.js'
+
+/**
+ * The semantic role of a node in the diagram.
+ */
+export type DiagramNodeKind = 'layer' | 'feature' | 'artifact'
+
+/**
+ * The semantic relationship between nodes.
+ */
+export type DiagramEdgeRelation = 'contains' | 'flows_to' | 'depends_on'
+
+/**
+ * A node in the diagram graph.
+ * Represents a semantic entity, not a visual element.
+ */
+export interface DiagramNode {
+  /** Unique identifier */
+  id: string
+  /** Human-readable label */
+  label: string
+  /** Semantic role */
+  kind: DiagramNodeKind
+  /** Feature maturity status (only for 'feature' nodes) */
+  status?: FeatureStatus
+  /** Semantic grouping (not layout instruction) */
+  layer?: string
+  /** Order within layer for pipeline semantics */
+  orderInLayer?: number
+}
+
+/**
+ * An edge connecting two nodes.
+ * Represents a semantic relationship, not a visual connector.
+ */
+export interface DiagramEdge {
+  /** Source node ID */
+  from: string
+  /** Target node ID */
+  to: string
+  /** Type of relationship */
+  relation: DiagramEdgeRelation
+}
+
+/**
+ * Complete diagram specification.
+ *
+ * This is the contract that crosses system boundaries.
+ * Backend produces it, clients consume it, renderers interpret it.
+ *
+ * IMPORTANT: No render hints. Renderers decide presentation.
+ */
+export interface DiagramSpec {
+  /** All nodes in the diagram */
+  nodes: DiagramNode[]
+  /** All edges connecting nodes */
+  edges: DiagramEdge[]
+}

package/system/index.ts

@@ -1,10 +1,15 @@
 /**
- * System Snapshot Types
+ * System Diagram Types
  *
  * Schema for the Living ASCII System Diagram feature.
  * These types define the contract between:
- *   - company-semantics (generates snapshots)
- *   - company-semantics-site (renders snapshots)
+ *   - company-semantics (produces semantic DiagramSpec)
+ *   - company-semantics-site (renders diagrams client-side)
+ *
+ * Architecture:
+ *   - Backend owns MEANING (DiagramSpec with nodes/edges)
+ *   - Client owns RENDERING (ASCII, SVG, etc.)
+ *   - No diagram artifacts are committed — runtime rendering only
  *
  * @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
  */
@@ -79,7 +84,8 @@ export interface SystemSnapshotMeta {
 
 /**
  * Complete snapshot bundle (ASCII + metadata).
- * Used when fetching/importing into the site.
+ * @deprecated Use DiagramSpec instead. This type will be removed in a future version.
+ * ASCII rendering now happens client-side from DiagramSpec.
  */
 export interface SystemSnapshot {
   /** Raw ASCII diagram content */
@@ -89,3 +95,12 @@ export interface SystemSnapshot {
   /** Optional explanation markdown */
   explanation?: string
 }
+
+// Graph-based diagram types (new architecture)
+export type {
+  DiagramNodeKind,
+  DiagramEdgeRelation,
+  DiagramNode,
+  DiagramEdge,
+  DiagramSpec,
+} from './diagram.js'