@company-semantics/contracts 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -46,6 +46,7 @@
     "guard:version-tag:json": "npx tsx scripts/ci/version-tag-guard.ts --json",
     "guard:test": "vitest run scripts/ci/__tests__",
     "release": "npx tsx scripts/release.ts",
+    "prepublishOnly": "pnpm guard:version-tag",
     "test": "vitest run scripts/ci/__tests__"
   },
   "packageManager": "pnpm@10.25.0",

package/src/index.ts

@@ -23,17 +23,19 @@ 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 diagram types (Living ASCII Diagram)
-// @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
+// System diagram types
 export type {
   // Layer-based manifest (source of truth)
   FeatureStatus,
   SystemCapability,
   SystemLayer,
   SystemCapabilityManifest,
-  // Graph-based diagram spec (v0.4.0)
+  // Graph-based diagram spec (v0.18.0)
   DiagramNodeKind,
   DiagramEdgeRelation,
+  EdgeDirection,
+  FlowStage,
+  DiagramMode,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,

package/src/system/diagram.ts

@@ -1,5 +1,5 @@
 /**
- * Diagram Specification Types (v0.17.0)
+ * Diagram Specification Types (v0.18.0)
  *
  * Tree-based semantic model for system diagrams.
  * These types define MEANING, not presentation.
@@ -9,6 +9,16 @@
  * - parentId creates hierarchy (tree structure), not edges
  * - Graphs can be rendered as React Flow, SVG, canvas, or any future format
  * - meta is opaque — engine interprets, contracts stay neutral
+ * - Edges represent semantic flow, not imports
+ * - Direction is encoded in edge data (authority in edge, not node)
+ *
+ * v0.18.0 changes:
+ * - BREAKING: DiagramEdgeRelation expanded (invokes, emits, authorizes, reads)
+ * - BREAKING: FlowStage renamed to architecture layers
+ * - Added 'repo' to DiagramNodeKind
+ * - Added EdgeDirection to DiagramEdge
+ * - Added DiagramMode for diagram projections
+ * - Added FlowStage for architecture layering
  *
  * v0.17.0 changes:
  * - BREAKING: Removed 'ascii' field from DiagramSnapshot (React Flow only)
@@ -32,16 +42,77 @@ import type { FeatureStatus } from './index.js'
 
 /**
  * The semantic role of a node in the diagram.
+ * v0.18.0: Added 'repo' for repository-level containment
  */
-export type DiagramNodeKind = 'group' | 'feature' | 'artifact'
+export type DiagramNodeKind = 'repo' | 'group' | 'feature' | 'artifact'
 
 /**
  * The semantic relationship between nodes.
  * Note: 'contains' removed in v0.4.0 — hierarchy now via parentId
  *
- * v0.5.0: Added 'feedback' and 'async' for richer flow semantics
+ * v0.18.0: Expanded to include authority-aware relations
+ * - invokes: Active call (e.g., app invokes MCP tool)
+ * - emits: Produces events/data (e.g., edge emits to backend)
+ * - authorizes: Trust boundary (e.g., backend authorizes access)
+ * - reads: Passive consumption (e.g., app reads strategy)
+ * - depends_on: Build/type dependency
+ * - feedback: Bidirectional loop
+ */
+export type DiagramEdgeRelation =
+  | 'invokes'
+  | 'emits'
+  | 'authorizes'
+  | 'reads'
+  | 'depends_on'
+  | 'feedback'
+
+/**
+ * Edge direction semantics.
+ * Determines which end of the edge has authority to update it.
+ *
+ * v0.18.0: New type for explicit directionality
+ */
+export type EdgeDirection = 'forward' | 'backward' | 'bidirectional'
+
+/**
+ * Architecture layers for horizontal organization.
+ * The primary organizing axis - determines which column a node belongs to.
+ *
+ * v0.18.0: Renamed from processing-pipeline to architecture-layer semantics
  */
-export type DiagramEdgeRelation = 'flows_to' | 'depends_on' | 'feedback' | 'async'
+export type FlowStage =
+  | 'clients'     // CLIENTS (ALL MCP CONSUMERS)
+  | 'authority'   // MCP AUTHORITY & TOOL GATEWAY
+  | 'truth'       // SEMANTIC TRUTH, STRATEGY, & EVIDENCE (AWS)
+  | 'edge'        // EDGE INGESTION & MCP ADAPTERS
+  | 'evaluation'  // EVALUATION, GUIDANCE, & AGENTS (MCP)
+  | 'governance'  // CI / GOVERNANCE
+
+/**
+ * Data lifecycle phase for coloring/filtering.
+ * Secondary annotation — does not affect layout.
+ *
+ * v0.19.0: New type for pipeline visualization
+ */
+export type PipelinePhase =
+  | 'source'     // External data origin
+  | 'ingest'     // Data collection and intake
+  | 'normalize'  // Schema alignment and transformation
+  | 'evaluate'   // Analysis and decision-making
+  | 'store'      // Persistence and retrieval
+  | 'surface'    // Presentation and delivery
+
+/**
+ * Diagram projection modes.
+ * One graph, filtered by mode.
+ *
+ * v0.18.0: New type for multi-view diagrams
+ */
+export type DiagramMode =
+  | 'file'         // Future: file-level (not implemented)
+  | 'capability'   // All capabilities visible
+  | 'repo'         // Repo containers + direct children only
+  | 'architecture' // Repo + exported capabilities only
 
 /**
  * A node in the diagram graph.
@@ -69,6 +140,8 @@ export interface DiagramNode {
 /**
  * An edge connecting two nodes.
  * Represents a semantic relationship, not a visual connector.
+ *
+ * v0.18.0: Added direction for authority semantics
  */
 export interface DiagramEdge {
   /** Source node ID */
@@ -77,6 +150,15 @@ export interface DiagramEdge {
   to: string
   /** Type of relationship */
   relation: DiagramEdgeRelation
+  /**
+   * Direction semantics for authority.
+   * - forward: Can only be updated from source (most common)
+   * - backward: Can only be updated from target
+   * - bidirectional: Can be updated from both sides (rare, explicit)
+   *
+   * Defaults to 'forward' if not specified.
+   */
+  direction?: EdgeDirection
 }
 
 /**

package/src/system/index.ts

@@ -1,5 +1,5 @@
 /**
- * System Diagram Types (v0.17.0)
+ * System Diagram Types (v0.19.0)
  *
  * Schema for the system diagram feature.
  * These types define the contract between:
@@ -11,6 +11,12 @@
  *   - Site displays interactive React Flow diagram
  *   - Snapshots pushed via CI automation
  *
+ * v0.19.0: PipelinePhase annotation for data lifecycle visualization
+ * v0.18.0: Semantic architecture diagram transformation
+ *   - Edge semantics (invokes, emits, authorizes, reads)
+ *   - FlowStage for architecture layers
+ *   - DiagramMode for projections
+ *   - 'repo' node kind
  * v0.17.0: Removed ASCII rendering (React Flow only)
  * v0.6.0: meta is now opaque (Record<string, unknown>), engine interprets
  */
@@ -65,6 +71,10 @@ export interface SystemCapabilityManifest {
 export type {
   DiagramNodeKind,
   DiagramEdgeRelation,
+  EdgeDirection,
+  FlowStage,
+  PipelinePhase,
+  DiagramMode,
   DiagramNode,
   DiagramEdge,
   DiagramSpec,