Novolis Visual architecture
Status: accepted implementation baseline
This repository owns host-neutral visual contracts, compilation, baking, code generation, and rendering adapters. It does not own AssetStudio implementation services, Avalonia, Silk.NET, a window, a GPU context, or a second scene hierarchy.
Existing authorities
Novolis.WorkflowEngine.Graph,.Flow,.Pipeline, and.FlowGraphown
topology, typed ports, linear composition, immutable graph snapshots, and structural diagnostics.
Novolis.Modeling.Sceneowns renderer-neutral scene documents, generators,
modifiers, staged evaluation, and evaluated meshes.
Novolis.Rendering.Scene,.Materials,.Compile,.Runtime, and backend
packages own render authoring, material lowering, compiled scenes, runtime buffers, acceleration structures, and path-tracing execution.
Novolis.Rendering.Appearanceowns the current serializable appearance
stack, CPU surface/volume/light/effect evaluation, recipes, and CPU baking.
Novolis.CodeGen.Pipelineowns offline step orchestration, fingerprints,
output checks, and cache records.
Novolis.Avalonia.*owns reusable Avalonia controls and chrome.Novolis.Silk.*is the only package family allowed to reference Silk.NET.
Visual packages adapt to these authorities. None of those lower-level authorities reference Visual or Asset Studio.
Package ownership
The first stable projects are:
Novolis.Visual.DefinitionsNovolis.Visual.CompileNovolis.Visual.EvaluationNovolis.Visual.BakingNovolis.Visual.CodeGenNovolis.Visual.Adapters.Rendering
AssetStudio authoring, import, export, and the PackAsTool command are owned by
the AssetStudio implementation in novolis-tools; the product host is owned
by novolis-apps. Novolis.Avalonia.AssetStudio is only the reusable chrome
and adapter surface.
Dependency rules
WorkflowEngine.Graph/Flow/FlowGraph
↓
Visual.Definitions
↓
Visual.Compile/Evaluation/Baking/CodeGen
↓
Visual rendering and modeling adapters
↓
Rendering and Modeling authoritiesThe visual compiler may consume FlowGraph; it never executes a graph per
frame. Novolis.Rendering.FrameGraph, when added, owns graphics resource
lifetimes and pass scheduling and does not depend on FlowGraph.
Cross-repository references use LibraryReference or package references.
ProjectReference mode is only an evaluation mode supplied by governance.
Committed projects do not contain sibling-checkout references or local feeds.
Current lab graduation
novolis-lab/labs/visual/AssetStudioLab is retained as a vertical-slice
fixture. Its tree AST, DSL, CPU evaluator, bake path, C# emitter, timeline
integration, and tests become migration fixtures for the stable packages.
The lab's RenderingVisualProgram and SilkVisualProgram remain neutral
handshake records until actual adapters are proven.
Architecture decisions
ADR-001: Visual ownership
Visual definitions and compilation live in novolis-visual, not
novolis-rendering. Rendering is a lower-level runtime authority and must not
depend on authoring schema, workflow execution, Roslyn, or editor services.
ADR-002: One semantic representation
VisualRecipe is canonical. Stack, graph, DSL, inspector, and generated C#
are projections or targets. Arbitrary C# is not promised to round-trip into a
recipe.
ADR-003: Geometry and mesh authority
Modeling owns geometry and scene evaluation. Rendering owns its runtime mesh
and material consumption. Visual adapters bridge the two and never introduce
a duplicate SceneDocument or universal render object.
ADR-004: Backend capability truth
Targets report exact, approximate, baked-fallback, or unsupported status. Unsupported procedural fields are baked or rejected; they are not silently replaced with a visually unrelated preview.
ADR-005: Frame graph separation
Novolis.Rendering.FrameGraph is renderer-specific and per-frame. It is not a
generic WorkflowEngine executor and is not the storage model for visual
recipes.
ADR-006: Code-only output
Code-only means no required external runtime files, editor assemblies, recipe JSON, graph interpreter, Roslyn runtime, or source paths. Embedded bytes, generated pixels, compressed mesh data, and shader strings are allowed when the export report records size and performance tradeoffs.
ADR-007: Host isolation
Visual core has no Avalonia or Silk.NET references. Avalonia controls live in
the Novolis.Avalonia.* family or the product host. Silk.NET remains inside
novolis-silk; visual targets exchange Math/BCL handshake payloads.