@company-semantics/contracts 0.3.0 → 0.5.0

package/index.ts

@@ -31,10 +31,11 @@ export type {
   SystemCapability,
   SystemLayer,
   SystemCapabilityManifest,
-  // Graph-based diagram spec
+  // 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.3.0",
+  "version": "0.5.0",
   "private": false,
   "repository": {
     "type": "git",

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,27 @@ 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.
+ *
+ * Invariant: The generator declares all write intent via generatedFiles[].
+ * CI will never infer or expand intent.
+ */
+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 (stringified for stability) */
+  manifestVersion: string
+  /** Schema version for forward compatibility */
+  specVersion: 'v1'
+  /** Files this snapshot will write (manifest-driven automation) */
+  generatedFiles: string[]
+}

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
  */
@@ -71,4 +71,5 @@ export type {
   DiagramNode,
   DiagramEdge,
   DiagramSpec,
+  DiagramSnapshot,
 } from './diagram.js'