@company-semantics/contracts 0.2.2 → 0.4.0

package/index.ts

@@ -31,14 +31,11 @@ export type {
   SystemCapability,
   SystemLayer,
   SystemCapabilityManifest,
-  // Snapshot metadata
-  SystemSnapshotMeta,
-  /** @deprecated Use DiagramSpec instead */
-  SystemSnapshot,
-  // Graph-based diagram spec (new architecture)
+  // Graph-based diagram spec (v0.4.0)
   DiagramNodeKind,
   DiagramEdgeRelation,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,
+  DiagramSnapshot,
 } from './system/index.js'

package/package.json

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

package/system/README.md

@@ -25,17 +25,13 @@ Defines the semantic contract between backend (producer) and site (renderer).
 - `SystemLayer` — logical layer grouping
 - `SystemCapabilityManifest` — full manifest structure (YAML representation)
 
-### Diagram graph (new architecture)
+### Diagram graph
 - `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)

package/system/diagram.ts

@@ -1,14 +1,21 @@
 /**
- * Diagram Specification Types
+ * Diagram Specification Types (v0.4.0)
  *
- * Graph-based semantic model for system diagrams.
+ * Tree-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
+ * - parentId creates hierarchy (tree structure), not edges
  * - Graphs can be rendered as ASCII, SVG, canvas, or any future format
  *
+ * v0.4.0 changes:
+ * - 'layer' kind renamed to 'group'
+ * - parentId replaces layer field for tree structure
+ * - order replaces orderInLayer
+ * - No 'contains' edges (hierarchy via parentId)
+ * - Added DiagramSnapshot for cross-repo distribution
+ *
  * @see ../docs/LIVING_ASCII_DIAGRAM_SPEC.md
  */
 
@@ -17,12 +24,13 @@ import type { FeatureStatus } from './index.js'
 /**
  * The semantic role of a node in the diagram.
  */
-export type DiagramNodeKind = 'layer' | 'feature' | 'artifact'
+export type DiagramNodeKind = 'group' | 'feature' | 'artifact'
 
 /**
  * The semantic relationship between nodes.
+ * Note: 'contains' removed in v0.4.0 — hierarchy now via parentId
  */
-export type DiagramEdgeRelation = 'contains' | 'flows_to' | 'depends_on'
+export type DiagramEdgeRelation = 'flows_to' | 'depends_on'
 
 /**
  * A node in the diagram graph.
@@ -35,12 +43,14 @@ export interface DiagramNode {
   label: string
   /** Semantic role */
   kind: DiagramNodeKind
+  /** Parent node ID for tree hierarchy (replaces layer field) */
+  parentId?: string
+  /** Order within parent for pipeline semantics */
+  order?: number
+  /** Whether this node can receive focus in interactive renderers */
+  focusable?: boolean
   /** Feature maturity status (only for 'feature' nodes) */
   status?: FeatureStatus
-  /** Semantic grouping (not layout instruction) */
-  layer?: string
-  /** Order within layer for pipeline semantics */
-  orderInLayer?: number
 }
 
 /**
@@ -70,3 +80,22 @@ export interface DiagramSpec {
   /** All edges connecting nodes */
   edges: DiagramEdge[]
 }
+
+/**
+ * Snapshot of a rendered diagram for cross-repo distribution.
+ *
+ * Backend generates this and pushes to site repo via CI.
+ * Includes pre-rendered ASCII so site doesn't need rendering logic.
+ */
+export interface DiagramSnapshot {
+  /** Pre-rendered ASCII art */
+  ascii: string
+  /** Semantic nodes for interactive features */
+  nodes: DiagramNode[]
+  /** ISO timestamp when snapshot was generated */
+  generatedAt: string
+  /** Version of the source manifest */
+  manifestVersion: number
+  /** Schema version for forward compatibility */
+  specVersion: 'v1'
+}

package/system/index.ts

@@ -1,15 +1,15 @@
 /**
- * System Diagram Types
+ * System Diagram Types (v0.4.0)
  *
  * Schema for the Living ASCII System Diagram feature.
  * These types define the contract between:
- *   - company-semantics (produces semantic DiagramSpec)
- *   - company-semantics-site (renders diagrams client-side)
+ *   - company-semantics-backend (produces DiagramSnapshot with pre-rendered ASCII)
+ *   - company-semantics-site (displays snapshot, interactive features)
  *
  * Architecture:
- *   - Backend owns MEANING (DiagramSpec with nodes/edges)
- *   - Client owns RENDERING (ASCII, SVG, etc.)
- *   - No diagram artifacts are committed — runtime rendering only
+ *   - Backend owns MEANING and RENDERING (DiagramSnapshot with ASCII + nodes)
+ *   - Client displays pre-rendered ASCII
+ *   - Snapshots pushed via CI automation
  *
  * @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
  */
@@ -64,43 +64,12 @@ export interface SystemCapabilityManifest {
   layers: SystemLayer[]
 }
 
-/**
- * Metadata accompanying a generated snapshot.
- */
-export interface SystemSnapshotMeta {
-  /** Metadata format version */
-  version: number
-  /** ISO 8601 timestamp of generation */
-  snapshotDate: string
-  /** Git commit SHA of source */
-  commitSha: string
-  /** Schema version used for generation */
-  schemaVersion: string
-  /** Visibility level (always 'public' for now) */
-  visibility: 'public'
-  /** SHA256 checksum of the ASCII content */
-  checksum?: string
-}
-
-/**
- * Complete snapshot bundle (ASCII + metadata).
- * @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 */
-  ascii: string
-  /** Snapshot metadata */
-  meta: SystemSnapshotMeta
-  /** Optional explanation markdown */
-  explanation?: string
-}
-
-// Graph-based diagram types (new architecture)
+// Graph-based diagram types
 export type {
   DiagramNodeKind,
   DiagramEdgeRelation,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,
+  DiagramSnapshot,
 } from './diagram.js'