stzGraph: Computational Foundation and Design

Core Philosophy

Most graph systems mix concerns—debug structure, understand domain logic. stzGraph is intentionally narrow: pure algorithms + introspection. Extensions (stzDiagram, stzEntity, stzRelation) add meaning.

What stzGraph Provides

Structural Analysis

• Path Analysis: Routes from A to B
• Reachability: All nodes reachable from X
• Cycle Detection: Circular dependencies
• Bottleneck Identification: Critical hubs
• Metrics: Density (coupling), longest path (depth)
• Neighborhoods: Direct in/out connections

Design Features: Visibility & Expressiveness

Visibility (Native ASCII Visualization) - Show() / ShowV() — vertical layout - ShowH() / ShowHorizontal() — horizontal layout - ShowWithLegend() — annotated with structural markers - Markers: !label! (bottleneck), //// (path separator), <CYCLE:> (loop), [Node] (cycle member) - Built-in, tool-independent, immediate feedback during development

Expressiveness (Structured Explanation) - .Explain() returns programmatic analysis: - general: node/edge counts - bottlenecks: hub nodes and degree distribution - cycles: cycle detection + risk assessment - metrics: density, longest path - Enables CI/CD validation, automated linting, structured reporting

Example:

if Explain()["cycles"][1].contains("WARNING")
    throw("Cycles detected—invalid structure")
end

Properties: Metadata Bridge

Nodes store metadata without interpreting it:

AddNodeXT(:@step, "Validate", :Process, ["priority" = "high", "owner" = "team-a"])

stzGraph keeps properties inert; domain layers interpret them (stzDiagram uses priority/owner; stzEntity adds cardinality/constraints).

Design Principles

Computational Purity: One implementation serves workflows, hierarchies, data flows, type systems, service maps.

Explicit Representation: All nodes/edges observable; no hidden state.

Algorithmic Safety: Visited tracking prevents infinite loops even in cyclic graphs.

Visibility & Expressiveness: Visualization and explanation are first-class features, not add-ons.

Problem Classes Solved

Natural Language Modeling: A Semantic Foundation

stzGraph enables coherent language models through validation-first design:

# Step 1: Model type hierarchy
oTypes = new stzGraph("TypeSystem")
oTypes.AddEdge(:@entity, :@person, "is_a")
oTypes.AddEdge(:@person, :@employee, "is_a")
oTypes.AddEdge(:@employee, :@manager, "is_a")

# Step 2: Validate before interpretation
if oTypes.CyclicDependencies()
    throw("Type system logically incoherent")
end

# Step 3: Use reachability for inference
aReachable = oTypes.ReachableFrom(:@person)
# Result: [Person, Employee, Manager] — what Person inherits

# Step 4: Find semantic alternatives
aAllPaths = oTypes.FindAllPaths(:@person, :@manager)
# Result: multiple inference routes if they exist

Benefit: Language models built on sound relational foundations. Type contradictions caught at graph level before semantic interpretation.

Layering: - stzGraph validates structure (acyclic? consistent? coherent?) - stzEntity adds constraints (cardinality, required fields, type rules) - Application interprets meaning ("Manager inherits all Person rules")

Comparison to Other Systems

When to use stzGraph: - Validate structure before semantic interpretation - Build domain layers (stzDiagram, stzEntity, custom) - Need quick structural feedback without external tools - Reasoning independent from domain logic

When to use NetworkX: - Extensive graph algorithms (centrality, clustering, matching) - Pure Python environment

When to use Neo4j: - Persistent, queryable graph storage - Production enterprise scale - Rich query language needed

How Softanza Approach Differs

Traditional: Graph + domain semantics + validation + rendering = monolithic.

Softanza: Separate layers.

stzGraph (algorithms + introspection)
  ↓ inherited by
stzDiagram (workflow semantics + rendering)
  or
stzEntity + stzRelation (type systems + constraints)
  ↓ inherited by
Application (business logic + interpretation)

Result: Test graph algorithms independently. Reuse across domains. Add semantics layerwise. Reason about structure vs. meaning separately.

Algorithmic Guarantees

• Correct: Valid results for any input
• Terminating: Always finish (no infinite loops)
• Efficient: O(V + E) complexity
• Deterministic: Same input → same output

Why This Design

Narrowness enables: - Testability: Verify algorithms without domain logic - Reusability: One implementation, many domains - Maintainability: Focused, stable codebase - Extensibility: New specializations inherit automatically - Transparency: Structure vs. semantics explicit - Developer Experience: Visualization + explanation built-in

Scope (intentional exclusions): - ✗ Sophisticated rendering (stzDiagram handles it) - ✗ Validation rules (domain layers handle it) - ✗ Type constraints (stzEntity handles it) - ✗ Persistence (specializations handle it)

Conclusion

stzGraph is computational foundation: pure, correct, introspectable algorithms for relational reasoning.

Specializations add meaning: - stzDiagram → workflows - stzEntity / stzRelation → language modeling - Custom → any relational domain

All build on the same foundation. Visualization and explanation make that foundation transparent. Separation of concerns makes it reusable.

Related reading

• Intelligence in Motion: Graph Planning in Softanza
• stzGraph — Modeling Knowledge Through Structure
• Introducing stzOrgChart - The Strategic Organizational Intelligence Platform
• stzGraph: The Art of Connected Thinking

Cite

Mansour Ayouni. "stzGraph: Computational Foundation and Design". Softanza narrations, 2025. https://mayouni.github.io/stzsite/en/narrations/stzgraph-computational-foundation.html

Run in Haro's name on 2026-10-08 20:43 inside the library at commit 4a184e6f0, block after block in one process: 0 of 3 blocks kept their promise; the others are illustrations. The code of the articles is Haro code. Where an article was written before the language took its present name, the name was changed and nothing else. Genre, area and series read from the file's name, the year from its first commit: derived, until the article carries its own header. The file on GitHub(opens in a new tab)